Passing Payload Values
In MomentScience, you can pass various customer and order details to Offers for different purposes. This documentation is all about efficiently passing payload values within the MomentScience ecosystem. By doing so, you can improve personalization, targeting, reporting, and integration efficiency.
- Offer Unit Personalization: : Utilize passed payload values as macros to personalize Offer messaging, making the user experience more personal. For instance, employ {{firstname}} to customize the header of the SOU, like 'John, Your Order is Complete!'.
- Enhanced Targeting: With payload values, you can target Offers more effectively, ensuring that the right content reaches the right audience.
- Customized Reporting: You can pass payload values to attribute your implementantions to generate reports to segragate performance and giving you deeper insights into your business performance.
- Supporting LoyaltyBoost Offers: Payload values facilitate rewarding users for engaging with partners through LoyaltyBoost Offers.
In MomentScience, certain attributes are reserved, meaning they already have predefined meanings attached to them. While our system allows passing any ad-hoc key-value pairs in the payload, it's important to be aware of these reserved attributes to avoid unintended behavior. These reserved attributes serve specific purposes within the MomentScience ecosystem.
Attribute | Description |
|---|---|
country | Restricts Offers by geographical location, overriding locality sensed by IP address. Should be in the ISO 3166-1 alpha-2 2-character country code format. Example: If the user is from the United States, the country value should be US |
adpx_fp | Used for unique user identification, frequency capping, and enables yield optimizations. This identifier can be any unique string or hashed value that represents a unique user. |
theme_id | Applies theme styles defined in the MomentScience Dashboard. |
ip | The IP address of the end user to be passed through. Only used as a reserved attribute for the following implementation methods: |
ua | The User-Agent of the end-user. Only used as a reserved attribute for the following implementation methods: |
dev | Controls impression recording and deactivates geo-filtering when itβs set to a value that evaluates to true |
tags | Accepts comma-separated lists or Javascript array objects. Only applies as a reserved attribute for passing payload values types for the following implementation methods: |
zipcode | Enables targeting based on 5-digit zip codes. If provided, it overrides the automatically identified zipcode from the incoming requestβs IP. |
age | Allows age targeting for personalized offers. |
source | Identifies how a session is being served (e.g., SDK vs. API). This attribute cannot be used as a custom payload attribute, as it serves a specific reporting function within the MomentScience system. While using "source" as a custom payload key will not result in an error, it will not be included in reporting. |
You can also add any number of custom key-value payload attributes to include additional details. These attributes are passed back on conversion reports and can be used for analysis related to impressions and clicks. Custom key-value payload attributes are also used by MomentScience to help match relevant Offers to your users.
For example, you can pass custom attributes like membershipID ,source , and interests.
Attribute | Description |
|---|---|
User email | |
firstname | User first name |
zipcode | User zip code |
mobile | User mobile number |
confirmationref | Can be used to associate a confirmation number with the MomentScience request. This reference can then be used in macros for personalizing MomentScience units to better suit your needs. |
country | The user country payload. Should be in the ISO 3166-1 alpha-2 2-character country code format. Example: If the user is from the United States, the country value should be US |
adpx_fp | Unique user identification that represents a unique user. |
To uniquely identify a user, MomentScience uses various signals and inferred uniqueness. However, you can provide your own identifier using the adpx_fpattribute.
This identifier can be any unique string or hashed value. It helps MomentScience utilize this value to distinguish individual users, applying frequency caps and preventing repeated displays of Offers when a user opts out.
To better analyze the performance of your MomentScience units and segment traffic, consider including a subid or placement attribute. Replace the value with any text you prefer to track impressions, clicks, and conversions to that attribute.
Along with using custom key-value attributes, you can use the tagsattribute to provide additional context for more relevant and personalized Offers. The tags attribute can have a value passed in as a comma-separated list of values or as a JavaScript array of strings.
The tags attribute only applies to the following types of implementations:
To pass a payload value using the Moments API, include key-value payload attributes within the API request body as a JSON object.
You have the flexibility to add any number of custom key-value payload attributes to provide additional details for your payload.
To pass a payload value using the Perkswall API, include key-value payload attributes within the API request body as a JSON object.
You have the flexibility to add any number of custom key-value payload attributes to provide additional details for your payload.
Payload values are specified within the properties of the window.AdpxUser object.
To pass payload values into Direct Offer Links, simply append any attribute-value pair to the end of the URL.
Example of a Direct Offer Link that includes two payload attributes: user_id and order_id:
The same method to add payload values in Direct Offer Links can be used on click_url values returned in the Offer Catalog APIο»Ώ response.
To pass payload values into Perkswall Direct Offer Links, simply append any attribute-value pair to the end of the URL.
Example of a Perkswall Direct Offer Link that includes two payload attributes: user_id and order_id:
π’ If you're running into any issues while going through the integration process, feel free to contact us at [email protected]