Add personalization to headless applications

15 Add personalization to headless applications

You can configure headless applications, such as native OS apps or custom web apps, to establish a visit context for each shopper by evaluating the shopper's audience membership.

This section applies to Storefront Classic only.

Audiences allow you to target content to certain groups of shoppers. You define an audience by creating a set of rules based on attributes of the shopper profile. See Define Audiencesfor information about audiences. Custom (that is, headless) applications call /ccstore/v1/audienceContext endpoints to use existing audiences to personalize content.

Before you begin adding personalization to a headless application, make sure that the following tasks are already complete:

Use the Commerce administration interface to create audiences and set locales and site settings.
Use the /ccadmin/v1/profiles endpoint to create shopper profiles.
Make sure the custom application can call the Commerce REST APIs.
Make sure the custom application conforms to the Internet Engineering Task Force (IETF) cookie spec RFC 6265. The application must be able to store cookies specified in REST responses and send them back in its REST requests.

View audience membership

You can use the REST API to pass a set of candidate audience IDs as query string parameters, and get a response that includes the subset of IDs (if any) that pertain to audiences a shopper belongs to. The must contain one or more of the following to identify the shopper:

Access token returned by the /login endpoint if the shopper is logged in or the soft-login cookie returned from the /login endpoint if the shopper logged in previously.
If the request does not include either of these, the shopper is considered anonymous.
Visit and visitor ID headers.
x-ccsite header that identifies the site.

For example:

GET
    /ccstore/v1/audienceMembership?filter=audience123,audience234,audience345
    Authorization: Bearer <access_token>

    x-ccsite: siteUS
    X-CCVisitId: <visit ID>
    X-CCVisitorId: <visitor ID>
    Cookie: SOFT_LOGIN=plM0UbcY....  <encrypted profile ID>

The following is an example of the response returned:

200 OK  
   {
       "audienceMembership": ["audience234", "audience345"]
   }

Shopper Profile rules

The Shopper Profile category includes attributes of individual registered shoppers who have logged in to a personal account. See Understand audience definitions for details about the available Shopper Profile attributes.

In order to personalize based on these profile attributes, the shopper must have a profile. Once a shopper has a registered profile, the custom application can log in the shopper by using the ccstore/v1/login endpoint. This endpoint sets a persistent cookie called SOFT_LOGIN that expires after 14 months. In order to personalize based in profile attributes, the call to /audienceMembership must contain either the access token or the SOFT_LOGIN cookie. Without either of these, the shopper is considered to be anonymous.

Geolocation rules

The Geolocation category includes attributes that identify the current geographical location of the shopper. See Understand audience definitions for details about the available Geolocation attributes.

If the custom application sends its requests through a content delivery network, like the storefront application does, then those requests, including the one to /audienceMembeship, will include an additional header. For example:

X-Akamai-Edgescape:
          georegion=263,country_code=US,region_code=MA,city=CAMBRIDGE,dma=506,pmsa=1120,areacode=617,county=MIDDLESEX,fips=25017,lat=42.3933,long=-71.1333,timezone=EST,zip=02138-02142+02238-02239,continent=NA
          ,throughput=vhigh,asnum=21399

This header is all the /audienceMembership endpoint needs in order to determine membership for Audiences with Geolocation rules. Otherwise, you must use the Store API to communicate geolocation data to the storefront server. Issue a PUT request to ccstore/v1/audienceContext/currentSession/geolocation/current. For example:

PUT
    ccstore/v1/audienceContext/currentSession/geolocation/current
    Authorization: Bearer <access_token>

    X-CCVisitId: <visit ID>

{
    "country_code": "US",
    "region_code": "CA",
    "city": "SANDIEGO",
    "timezone": "(GMT+11:00)",
    "latitude": -25.4
}

This request must include the X-CCVisitId header, which specifies the visit ID that is unique to a user session. The storefront server uses the value of this header as the key to the cache where this data is being stored. The same visit ID must be sent in the /audienceMembership call, even if the shopper is not currently logged in.

All the fields in the request are optional. The custom application sends only the fields used in the audience rules required for personalization. There is one exception: If a city is used in a place rule, country_code must be sent along with city to disambiguate the city. To find the place fields for any city, region, or country, query the /ccadmin/v1/places endpoint.

Entry Page and Entry Page Query Parameter Rules

Entry Page and Entry Page Query Parameter attributes specify how the shopper arrived at the storefront. These rules can be based on landing page URL, referring site, or a variety of default UTM and custom query string parameters. See Understand audience definitions for details about these attributes.

Send Entry Page and Entry Page Query Parameter information to the server by issuing a PUT request to ccstore/v1/audienceContext/currentSession/entryPage/current. For example:

PUT
    ccstore/v1/audienceContext/currentSession/entryPage/current

{
    "URL": "?a=a1&c=c1&d=d1&a=a2&e=",
    "Referer": "http://myserver.example.com"
}

Both the landing page URL (URL) and referring site (Referer) fields are optional. The request needs to send only the data to determine membership based on Entry Page and Entry Page Query Parameter audience rules. Note that query parameters are conveyed in the URL field. If audience rules depend only on the parameters and not the actual landing page URL, the value for the URL field can omit the URL as long as it contains the parameters starting with a ? character.

Device rules

Device attributes specify the type of device (such as a computer, tablet, or phone) and operating system (such as iOS or Android) the shopper is using to access the site. See Understand audience definitions for details about Device attributes.

Send device information to the server by issuing a PUT request to ccstore/v1/audienceContext/currentSession/deviceType/current. For example:

PUT
    ccstore/v1/audienceContext/currentSession/deviceType/current

{
    "deviceType": "Mobile",
    "deviceOS": "iOS"
}

Send information in a single request

You can send geolocation, entry page, query parameter, and device information in a single request by issuing a PUT request to ccstore/v1/audienceContext/currentSession. For example:

PUT
    ccstore/v1/audienceContext/currentSession

{
    "geolocation": {
        "country_code": "US",
        "region_code": "CA",
        "city": "SANDIEGO",
        "timezone": "(GMT+11:00)",
        "latitude": -25.4
    },
    "deviceData": {
        "deviceType": "Mobile",
        "deviceOS": "iOS"
    },
    "entryPage": {
        "URL": "?a=a1&c=c1&d=d1&a=a2&e=",
        "Referer": "http://myserver.example.com"
    }
}

Sending a PUT request to the base ccstore/v1/audienceContext/currentSession endpoint will replace all the data for each of the child endpoints, so use this endpoint only if you want to send all the data at once.

Browsing rules

Browsing attributes let you track shopper browsing behavior, that is, views of products or collections, in the current visit. See Understand audience definitions for details about Browsing attributes.

The ccstore/v1/audienceContext/addBrowsingEvent endpoint caches behavioral events. The custom application must call this endpoint with a X-CCVisitId header and pass in the ID of the viewed item, the catalog ID, and whether the viewed item was a product or collection.