Personalization API Best Practices

Personalization API Best Practices


Below are a few best practices to ensure you are working with the Button Personalization API as efficiently as possible.

When to make this request:

The Personalization API is a server-side integration between the Publisher CMS and Button. Upon client-side initialization, the Publisher CMS should call Button’s Personalization API in the appropriate request format with the required fields. Button will use the identifiers to determine offers the user is eligible for with partnered Brands, and return the full list of eligible offers. These offers can then be served back to the client-side to load the initial rendering of offers for your user.

API Call Frequency:

The Personalization API should be called every time a user requests to view on behalf of each user prior to showing the user an offer. Every time your client calls your CMS for an offer to display, you should also be calling Button to identify the optimal rate to show for that specific user.

Optimize for Low Latency:

The Button Personalization API has an average latency of ~100ms. To ensure optimal performance, keep TCP connections alive and reuse them when possible via connection pooling. If connection pooling is not used, new connections + TLS handshakes result in multi-roundtrip operation between the client and server and therefore higher latency when making these API calls.

Caching:

Do not cache when using the Personalization API. Since a user can change audiences at any time, you do not want to cache the rates you receive. You should fetch from the Personalization API each time a user initializes a session with your application.

Retry Logic:

If you do not receive a response from the Personalization API, you should employ a retry strategy with a cap and backoff. Button recommends waiting to display rates to users until you receive a response.

Tracking Commission from Publisher Offers:

As a helpful way to track commissions for the offers being tapped, the Personalization API responds with an id for every item within the offers collection. On the client-side, this offer ID can then be set in the pubRef property as part of the PurchasePathRequest when interacting with the Button SDK. If a transaction takes place downstream from one of your Publisher offers, you’ll be able to see this offer ID when ingesting Button webhooks for finalizing commissions back to the user selected the offer.

We have found most Publishers leverage the pubRef field most effectively when they encode this offer id along with the listed commission against their click ID.

Constructing Offers:

When constructing an offer, the Personalization API also provides a display_params property wherever possible within the offers collection items. Information in this property is often used when populating Brand offer templates shown to users. Since information within display_params is subject to change at the Brand’s discretion, we do not recommend using display_params as a way to reference offers within a Publisher’s CMS. Instead, a Publisher can use the merchant_id when mapping offers being stored within a Publisher’s CMS from the Personalization API.