Einstein Recommendations

The Einstein Recommendations API has two main functions: to receive activities and to output recommendations. Our customers can also achieve flexibility in switching recommenders without any code changes by using our Zone components.

This API documentation is primarily intended for Salesforce Commerce Cloud customers.

Enabling Access

To enable access to the Einstein Recommendations API, go to the Einstein Configurator, and input your Commerce Cloud Account Manager client ID in the API page. Using Site Administrator access, you can create the necessary client ID on the Account Manager page. For more information, see Add an API Client ID.

When enabled, and as long as the correct client ID is passed, the API functions in all environments, including production, staging, development, and sandbox instances.

Authentication

Each API call must pass the x-cq-client-id header for API key authentication.

Implementing our API on the client side or server side comes with some tradeoffs. To ensure that you keep your client ID secret, we recommend that you implement our API on the server side for increased security. Client-side implementation runs the risk of exposing your client ID to bad actors.

The requests to get recommendations, and certain user activities like viewProduct, viewReco, and clickReco, require caching considerations if implemented on the server side. For example, in the case of a user viewing a cached product page, the viewProduct activity should still be sent. It is important that Einstein receives all events, and that recommendations are not cached.

Usage Considerations

When using the Einstein Recommendations API, note this information.

API Email Limitations

This Einstein Recommendations API is not designed for the email recommendations use case. It does not support embedding Einstein recommendations in emails.

Scalability

Our service is globally distributed, horizontally scalable, and can automatically scale up and down based on traffic, so load testing is unnecessary. We recommend that you avoid any load testing because it affects recommendation results.

User Identifier Parameters

To help generate relevant product recommendations for each shopper, the Einstein Recommendations API provides parameters for shopper identification.

To avoid potential malicious activity, user identifier parameters must be non-sequential. The parameters should not include sequences, patterns, IP addresses, email addresses, names, or anything linked to a specific person. All user identifier parameters must comply with General Data Protection Regulation (GDPR) through hashing or other methods.

  • cookieId (required) - Unique identifier of an anonymous shopper. Typically, the cookieId is the value of a first-party cookie.
    • When making API requests from a traditional Commerce Cloud storefront, pass the cqcid cookie value to match the automatic activity tracking on the traditional storefront. For more information, see Browser-Based Local Data Storage.
    • When using OCAPI or the Salesforce Commerce API, use the visit_id value from the guest login response to match automatic activities. For more information, see the OCAPI Customer Document.
  • userId (encouraged) - Unique identifier of a logged-in shopper. This parameter enables Einstein to link the same logged-in user across multiple devices.
    • When making API requests from a traditional Commerce Cloud storefront, use the cquid cookie value to match automatic activity tracking on the traditional storefront. For more information, see Browser-Based Local Data Storage.
    • When using OCAPI or the Salesforce Commerce API, use the hashed_login value from the registered login response to match automatic activities. For more information, see the OCAPI Customer Document.

Reporting

Standard performance reporting for recommenders used through the Einstein API is the same as that for other recommenders used on your digital sites. You can view reporting on Einstein Reports and Dashboard (see this document to learn more about Einstein Reports and Dashboard).

To make separate reporting and troubleshooting easier, we recommend that you create separate recommenders for the Einstein API. For example, naming a recommender “pdp-mobile-API” indicates that the recommender is used on the product detail page on a mobile app.

Note: Reporting metrics are based on activities. If an application using the Einstein Recommendations API fails to send activities, all metrics for the API recommender appear as zero (0).

Rights of ALBERT EINSTEIN are used with permission of The Hebrew University of Jerusalem. Represented exclusively by Greenlight.