Concept overview
To plan your External Content connections effectively, take a look at the overview of the most important elements to understand their role in data processing and personalization.
| External Content Connection |
The basic unit of External Content personalization. |
| Reference fields |
Reference fields are used to filter your data and to match it to contacts in some cases. External Content sends you the values corresponding to these key fields in API requests. You can define multiple reference fields in an External Content connection. |
| Response fields |
Response fields contain the data to be inserted into your messages. You can define as many response fields in the External Content connection as many different data items can be requested from the same endpoint. The response fields are the fields you send back to External Content in your API responses. |
| Personalization preset |
In personalization presets, you have to refer to the External Content connection to be used. This prescribes the available reference fields in your personalization token. In your preset, you have to use every reference field of the chosen External Content connection. Additionally, you also have to define how the personalization token will use your reference fields. (As static values, matching contacts or expecting their values from External Events. For more information, see Personalization use cases and Omnichannel personalization - Creating a token category.) |
| Personalization token |
The main use of the token is to specify a single response field from the response fields of an External Content connection which will be inserted in your messages at the location of your token. Personalization tokens use the reference fields of an External Content connection through the personalization presets. |
In the following image, you can see that multiple presets can use the same External Content Connection.
You can use the same preset for multiple tokens if you need the same reference fields. However, you have to create a token for each response field you want to insert into a message.
The following table shows an overview on the relation of reference and response fields to connections, presets and tokens.
| External Content Connection | Personalization Preset | Personalization Token |
|---|---|---|
|
Defines:
|
Uses:
(also defines how the reference fields are interpreted) |
Uses:
(also defines: Item Index, Requirement for Setting checkbox, Fallback Text, Formatting settings) |
Different personalization use cases require different number of reference fields and different personalization token settings depending on the data you use.
It is recommended to keep as few External Content connections as possible for easier organization, although there is no limit on their number.
Even though there is no limit for the number of reference or response fields, consider your response size when adding multiple response fields. We do not have a character limit on the fields, but the whole body must not exceed 2MB. We recommend sending gzip-encoded responses.
Personalization use cases
To use the External Content add-on efficiently, consider the following before starting the setup:
1. Define the data you want to insert into your messages.
Each personalization token can have only one response field, therefore, it can insert only one value into your messages.
You can define multiple response fields in one External Content connection, but you have to define a token for each of them.
2. Plan the number of API endpoints needed to access these values.
Each External Content Connection can have a single API endpoint defined.
3. Think about how you can identify this data in your data sources using the reference fields in your token presets:
- Do you want to send unique data matching individual contacts?
You will need to uniquely identify your contacts both in the Emarsys and in your database using reference fields. Then you need to match the external data with the data in the Emarsys database in the personalization token’s preset. This is done by pairing your reference fields to the corresponding Emarsys contact field in the preset. This use case requires as many reference fields as needed to select a contact uniquely.
(Example: You would like to return the User Name of your contacts stored in your database. This will be your response field. Choose a reference field which contains a value unique to your contacts (for example, email address), and has a corresponding field in the Emarsys database. Set this as a Contact Field during preset creation.)
- Do you want to send data relevant only to specific categories or groups ?
You can solve this scenario by manually entering a value available in your data. This is achieved by selecting the Constant parameter type during personalization token present creation.
(Example: You would like to send product recommendations to all your contacts based on your product categories. Select “product category” as a reference field, and enter the name of the relevant product category in the personalization token preset. As a response field, set, for example, the image url of the specific recommended product. By using multiple tokens, each with a different category typed in as a reference field constant, you can cover your range in a single message.)
- Do you need to send information based on sudden events?
Use the External Event preset option during personalization token creation. This preset setting enables choosing specific external events and their keys in their JSON object body. This allows you to use event based data from external sources together with contact data from the Emarsys platform if necessary. For example, you can use Abandoned Cart events as an input for your product recommendation logic. For instance, the product IDs in the event can be used by you to create the recommendation.
For more information on creating these objects, see Omnichannel personalization - Creating a token category and Trigger an External Event.