Personalize with the Real-time API

Request-time personalization recognizes a returning customer when they arrive on your website or open your app, and shapes what they see from what Amperity knows about them: the products you feature, the offers you show, and the message you lead with. Your website, app, or personalization service reads the customer’s real-time profile and real-time segment memberships through the Real-time API while it builds the response, and sends the customer’s in-session behavior back to Amperity as events so that later reads reflect it.

How request-time personalization works

Personalization is a read: given an identifier for the visitor, retrieve the customer’s profile while the page or screen is being built. The Real-time API separates reads from writes:

• Reads are synchronous. Looking up a profile, reading a profile, and listing a profile’s segment memberships return the profile’s current state.

• Writes are asynchronous. Sending an event returns 202 Accepted once Amperity accepts the event for processing, before the event has updated the profile. A read made immediately after a write may not reflect that event yet.

For the request and response details of every endpoint, and to send test requests, see the Real-time API reference.

Before you begin

This integration needs:

• A profile collection bound to your customer 360 database, with the attributes your experience personalizes on. See Choose the attributes to serve.

• An event stream that the collection subscribes to, if you send in-session behavior.

• An access token from an API key with the permissions each request needs. Every request sends the token and identifies the tenant in the amperity-tenant header. See Permissions and tenancy for the permissions each endpoint requires, and How to authenticate with Amperity APIs to generate a token.

Call the Real-time API from your server or personalization service, and pass the result to the page or screen. The Real-time API accepts browser requests only from Amperity’s own HTTPS origins, and a request made from a browser or an app would expose the access token to anyone who inspects it.

Choose the attributes to serve

A lookup returns the profile’s attributes, so the collection’s attributes are what your experience can personalize on. Choose them for the decisions the experience makes:

• Database attributes for history and predictions that Amperity builds in batch: value tier, lifetime order count, loyalty status, preferred store, and predicted scores such as predicted customer lifetime value or product affinity. Database attributes come from tables in the collection’s database that have an amperity_id column, and update after each run of that database when Automatically refresh profiles after each database run? is selected on the collection.

• Event attributes for in-session behavior: the most recent product or category viewed, the current cart, and counts of recent views by category over a Lookback window.

• Computed attributes for decisions that combine both, such as whether a high-value customer has an item in their cart, written in Amperity’s expression language.

Send in-session events

Send the customer’s behavior during the session–page views, product views, searches, and cart changes–to the event stream with POST /prof/events/{stream-id}. Each event is a JSON object of up to 64 KiB. Each event carries a linking-key field, such as an email address, a loyalty ID, or a device identifier, that the event type maps to the collection’s keychain, so that Amperity can match it to the customer’s profile.

Event attributes update as the events are processed, so a later lookup in the same session can personalize on what the customer just did, not only on their history.

Look up the profile

Look up the customer by the identifiers you have for the visitor:

• Look up by identifier. GET /prof/lookup/{collection-id}/keychain with one or more identifiers as query parameters, such as ?email=..., or POST to the same path with the identifiers under keys in the request body, such as {"keys": {"email": "..."}}. Amperity tries the identifiers in the collection’s keychain priority order and returns the first profile that matches.

• Read by Amperity ID. When you already have the customer’s Amperity ID, such as from an earlier lookup in the session, read the profile with GET /prof/profiles/{collection-id}/{profile-id}.

The identifiers you have differ by surface:

• Website. An email address or loyalty ID once the visitor signs in, or any other identifier your site stores that is a linking key in the collection’s keychain.

• App. A customer ID or loyalty ID from the signed-in account, or a device identifier that your app’s events send as a linking key.

A lookup with no identifiers returns 400.

Read segment membership

Where the experience depends on an audience, such as showing an offer to customers in a “lapsed high value” segment, read the profile’s real-time segment memberships with GET /prof/profiles/{collection-id}/{profile-id}/segments. The response lists each segment’s ID and name. It is paginated with limit and next_token.

The profile response does not include segment memberships, so personalizing on both attributes and segments takes two requests: the lookup, then the segment read with the profile ID the lookup returned.

Handle visitors Amperity doesn’t recognize

A lookup that matches no profile returns 404, and so does a read by an Amperity ID that is not in the collection. Treat a 404 as an unrecognized visitor and serve your default experience.

A lookup matches when one of the visitor’s identifiers is in the collection’s keychain. The keychain is built from Stitch output and refreshed after each run of the collection’s database, and it also grows as events arrive: a visitor whose identifier arrives on an event has a profile shortly after that event is processed, through just-in-time profile creation. A visitor whose identifier Amperity has never seen, on an event or in Stitch, has no profile. See Identity recognition.