Below are a few best practices to ensure you are working with the Button Personalization API as efficiently as possible.
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.
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.
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.
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.
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.
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.
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.