Personalize API Flow execution
You can use the Personalize REST API flow execution service to run a flow for an interactive experiment or experience. You can do this over any web-based or mobile application, so you can personalize dynamic offers or content in real-time. For example, you can nudge the guest onto the next page or encourage them to add a product to their cart or order.
Characteristics of the flow execution service:
- Facilitates personalization in interactive experiences and experiments
- Invokes real-time responses
- Supports using decision models in interactive experiments to return the next best offer or action
When you send a flow execution request, you can only use one of these attributes; browserId, email, or identifiers. We recommend that you use the browserId attribute to execute a flow. This ensures that any goals the marketer added to the interactive experiment or experience are attributed to the correct browser session, the conversion is counted, and the attribution rate is accurate when the marketer views performance analytics.
There are some scenarios where you might not be able to use the browserId attribute to execute a flow, for example, if the browserId isn't persisted. Another example is if you send the output of a decision model in real-time to an external system such as a marketing cloud, for which the browserId attribute isn't relevant. For both these scenarios, we recommend using the email or identifiers attribute to execute the flow.
The following table describes flow execution model attributes:
| Attribute | Type | Description | Example(s) |
|---|---|---|---|
clientKey | string | The client key retrieved from Sitecore Personalize. | "mhbWwbHYfhpheu86hp60oR76S4jQMmZr" |
channel | string (uppercase) | The channel captured on each page the guest visited. The default is "WEB". | "WEB", "MOBILE_WEB", "MOBILE_APP" |
language | string (2 letter ISO 639 language code) | The language captured on each page the guest visited. | "EN", "FR", "DE" |
currencyCode | 3 letter ISO 4217 | Your organization’s currency code. | "EUR", "USD", "NZD" |
pointOfSale | string (predefined by your organization) | The point of sale used. | "myretailsite.com", "retailsite.co.uk" |
browserId | string | The ID of a browser generated by Sitecore Personalize. | "56860bff-94ba-4d84-aa37-2b5a83d5411b" |
email | string | The guest's email address. | "[email protected]" |
identifiers | JSON object | The unique identifiers of the guest. | N/A |
params | JSON object | The parameters returned from the visitor's current URL. | N/A |
The following table describes identifiers object attributes:
| Attribute | Description | Type | Example(s) |
|---|---|---|---|
provider | The identifier provider. | string | "ProfileSystem" |
id | The identifier identification. | string | "B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41" |
The following table describes params object attributes:
| Attribute | Description | Type | Example(s) |
|---|---|---|---|
utm.campaign | The UTM campaign parameter included in the visitor's current URL. | string | "content_promotion" |
utm.source | The UTM source included in the visitor's current URL. | string | "bing" |
utm.medium | The UTM medium included in the visitor's current URL. | string | "social" |
utm.content | The UTM content included in the visitor's current URL. | string | "call_to_action" |
The friendlyID
You can programmatically run experiments and experiences using the friendlyID attribute. When you create an experiment or experience, Sitecore Personalize automatically creates an ID when you name the experiment or experience. For example, if you name an experiment Product Recommender, Sitecore Personalize automatically generates an ID named product_recommender.
In some organizations there might be several variations of an experiment named Product Recommender that have different page targets, audience filters, or other conditions that must be met in order for the experiment to run.
To use this same example, users might intentionally delete some of the experiments named Product Recommender after the marketing campaign is retired. This can often happen across regions. To support referential integrity, Sitecore Personalize automatically appends a numeral to the value of the friendlyID attribute if the name of the experiment you create is identical to any names of deleted experiments. For example, Sitecore Personalize automatically appends a numeral 2 so the friendlyID attribute value is product_recommender_2.
To apply fuzzy matching so that Sitecore Personalize executes the first lexicographical match of the friendlyId, you pass in product_recommender* as the value for the friendlyID attribute. You can use an asterix to apply lexicographical order and execute the first live experment that matches and passes any other conditions such as page targeting and real-time audience filters.