Use recommendations in personalization campaigns

After you create a new recommendation, integrate it into your personalization campaigns. This article describes how to use the Profile API for that process.

Deploy your recommendation

The primary destination for deploying a recommendation is Amplitude’s Profile API. You can call this real-time API by user ID or device ID. In less than a second, Amplitude returns an array of information about the user.

You can give a recommendation access to the Profile API by navigating to the Syncs tab and selecting the Profile API as a destination for the recommendation.

The API

The Profile API is a REST endpoint. Query it by user ID or device ID to receive JSON responses for each user:

https://profile-api.amplitude.com/v1/userprofile

To authenticate to use the API, use the Secret Key from the project settings in Amplitude (Settings → Projects → [select project] → General).

Set query parameters to specify the user ID and recommendation. The API returns results as a JSON response body.

The following example request returns results for a specific user and recommendation. Find the recommendation ID in the Details section of a recommendation page.

bash

curl -H "Authorization: Api-Key Secret-Key" 'https://profile-api.amplitude.com/v1/userprofile?user_id=myuser&rec_id=s234ssg'`

A sample response for this query is:

json

{
  "userData": {
    "recommendations": [
      {
        "rec_id": "s234ssg",
        "is_control": true,
        "items": [
          "investing-101",
          "mortgage-rates-primer",
          "retirement-goals",
          "what-is-a-cd",
          "setting-up-direct-deposit"
        ],
        "recommendation_source": "recommendations_model_v2",
        "last_updated": 1614192260
      }
    ],
    "user_id": "myuser",
    "device_id": "bef34a71-62cd-5b2e-af2f-58cd2eabb4d9",
    "amp_props": null
  }
}

The response contains three key pieces of information:

rec_id: The unique identifier of the recommendation.
is_control: A true or false result that indicates whether the user is in the control or treatment for the recommendation.
items: An array of strings. Amplitude orders items by predicted likelihood to optimize the outcome, with the highest-probability item first.

You can also use the API to retrieve user properties, predictions, and cohort membership. The following example sends a request to retrieve a recommendation, all user properties, a prediction, and cohort memberships:

bash

curl -H "Authorization: Api-Key Secret-Key" 'https://profile-api.amplitude.com/v1/userprofile?user_id=myuser&rec_id=s234ssg&get_amp_props=true&prediction_id=t456tth&get_cohorts=true'

A sample response for this query is:

json

{
  "userData": {
    "user_id": "myuser",
    "device_id": "bef34a71-62cd-5b2e-af2f-58cd2eabb4d9",
    "amp_props": {
      "country": "United States",
      "city": "Springfield",
      "first_used": "2019-04-30",
      "language": "English",
      "carrier": "Verizon",
      "last_used": "2021-02-25",
      "plan_type": "starter",
      "device": "samsung samsung SM-N976V",
      "os": "android 30",
      "app_version": "6.1.0",
      "gp:membership_points": "1752",
      "gp:initial_utm_campaign": "abcd",
      "gp:email": "user@example.com"
    },
    "recommendations": [
      {
        "rec_id": "s234ssg",
        "items": [
          "investing-101",
          "mortgage-rates-primer",
          "retirement-goals",
          "what-is-a-cd",
          "setting-up-direct-deposit"
        ],
        "is_control": false,
        "recommendation_source": "recommendations_model_v2",
        "last_updated": 1614192260
      }
    ],
    "predictions": [
      {
        "name": "Likelihood to Convert",
        "percentile": 97.5,
        "pred_id": "t456tth",
        "probability": 0.734
      }
    ],
    "cohort_memberships": ["u567uui"]
  }
}

Integrate the API

The Profile API makes embedding recommendations into a customer’s digital workflows extensible. To integrate the API, follow these steps:

Call the API:
- Pass in a user ID or device ID to retrieve a user profile.
- Make calls in real time during a user session to retrieve the most recent user profile at the moment of the call.
- Make calls at application startup and cache the profile throughout a user session. The Profile API returns with low latency and handles reasonable traffic volume, but caching can reduce latency variability. The tradeoff is that results may be less fresh. In most cases, cached results remain valid for several hours or longer.
- Don't publish the application-level secret key to client-side apps or web source code. Use a backend or proxy to validate user identity and forward requests to Amplitude’s API.
After the API returns a response, decide which recommended experience to serve by checking the value of is_control:
- If false, use items in the recommended payload.
- If true, default to the baseline product experience. Amplitude populates items with a random selection of items, which may or may not be a good baseline.
- If the recommendations block is null, or the API returns an error, default to the baseline product experience. This means either Amplitude doesn't yet know the user, or the user doesn't have enough history to provide recommendations.
Match the returned items from the payload with your internal CMS or feature flagging system to indicate which items to serve to the user.
Integrate the API with your delivery system.
- If serving users through an internal system, follow your normal delivery method.
- If serving experiences through Braze connected content, follow these instructions.
- If serving experiences through Movable Ink, follow these instructions.

Analyze your results

After you deploy the Profile API into a customer’s app, website, or email channels, Amplitude Activation can measure recommendation performance. Amplitude logs an event, [Recs] Recommendation Event, every time the Profile API is called for that specific recommendation.

This event doesn't count against your event volume.

To view the performance of your recommendation, open the recommendation you’re interested in and click on the Performance tab.

Amplitude shows summary stats from a funnel conversion chart:

Lift against baseline.
Recommendation conversion rate.
Control conversion rate.
Significance.

Amplitude defines "significance" as the value of 1 - *p*, where p comes from a two-sided t test. In some cases, certain previously saved charts may still display chance to outperform to maintain consistency with past results.

This funnel compares two segments: a control segment and a treatment segment. For the control segment, recommendations.recommendation_control = True. For the treatment segment, recommendations.recommendation_control = False.

The default funnel consists of two steps: the exposure event and outcome event. You can update these steps manually if needed. The funnel shows a comparison of the two segments over time.

To determine whether the difference between the Control and Treatment segments is statistically significant, check the value in the Significance column.

Use these results to quantify each recommendation's impact.

Was this helpful?