Passing Payload Values
Overview
MomentScience supports passing customer and order attributes, referred to as payload values, into offer units and APIs. These values enable dynamic personalization, advanced targeting, detailed reporting, and real-time data synchronization.
Payloads enhance the user experience and improve campaign performance by customizing content based on known attributes, such as firstname, email, or placement.
Payload values can be received back via Conversion Postbacks. These values enable real-time integration and synchronization of conversion data with external systems, allowing immediate updates based on user actions
What Payloads Enable
- Personalized Creatives: Use macros (e.g., {{firstname}}) in Offer Creatives to display personalized messages like: βJohn, your order is complete!β
- Advanced Targeting: Deliver Offers based on payload conditions like geography, age, or zip code.
- Attribution & Reporting: Track performance using custom parameters to understand where and how users interact with offers.
- LoyaltyBoost Offer Support: Attribute user activity to specific partners and unlock loyalty rewards using identifiers such as loyalty_program_id.
- Conversion Postbacks: Payloads are returned in postbacks to facilitate real-time syncing of conversion events with your backend or CRM systems.
Guidelines for Passing Payloads
To ensure consistent performance and avoid unintended behavior, follow these best practices when passing payload values:
- Up to 10 custom attributes are supported per request.
- We recommend keeping each value under 128 characters to ensure efficient processing and prevent misuse (e.g., excessive data storage).
- There are no enforced restrictions on attribute names, but they should be alphanumeric and use underscores where necessary.
- While no hard limits are currently enforced, character or attribute limits may change in future versions of the platform without prior notice.
- Avoid including sensitive PII beyond what is necessary.
Passing Payload Values
Required Attributes
The following are critical for basic functionality and must be included when passing payload values:
Attribute | Description |
|---|---|
placement | Identifies the page or screen where the offer was shown. Useful for analytics and segmentation. Example: checkout_confirmation_page |
pub_user_id | Required only when integrating with User Selected Perks (USP) or PerksWallet. This is a unique, non-PII identifier for each user.
|
Reserved Attributes
MomentScience supports flexible key-value payloads, but certain attributes have predefined behavior within the system. These reserved attributes control how offers are targeted, styled, or reported. Using them correctly ensures accurate behavior across all MomentScience products. avoid using these reserverd attribures rfor a differnet purpos
Attribute | Description |
|---|---|
country | Used to target offers by geographic location. If provided, this value overrides the location inferred from the user's IP address. Should be in the ISO 3166-1 alpha-2 2-character country code format (e.g., US, CA, GB) |
adpx_fp | Represents a unique user identifier. This value is used for deduplication, frequency capping, yield optimization, and user-level reporting. It should be a stable, non-PII string (e.g., hashed ID, UUID) that remains consistent across user sessions. |
theme_id | Applies custom styling and themes defined in the MomentScience Dashboard. Use this to match the look and feel of your offer unit to your site or brand. |
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 string from the end user's browser or device. This is useful for advanced targeting and is only supported by:
|
dev | Flags the request as development or test. If set to true, it disables geo-filtering and allows internal testing without affecting production analytics. |
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 by 5-digit ZIP code. If included, it overrides the ZIP code inferred from the user's IP address. |
age | Allows age-based targeting. Use this attribute when running age-sensitive offers or campaigns that require demographic segmentation. |
Custom Key-Value Attributes
You can pass custom key-value payload attributes to include additional details, which are included in conversion reports and used to analyze impressions, clicks, and user behavior. These payloads also help match relevant Offers to users.
Custom key-value payloads provide two key advantages:
- Real-time sync with your systems via Conversion Postbacks.
- Custom analytics and performance segmentation.
membershipID: "A45GRE987343PKD",
source: "email",
interests: "gardening"Recommended Attributes
The following payload attributes are not required but are strongly recommended. Including them improves offer targeting, personalization, and reporting capabilities across MomentScience products.
Attribute | Description |
|---|---|
The user's email address. While this is PII, it may be used if your implementation and privacy policies support it. Helps personalize offers or connect users to their transaction history. | |
firstname | The userβs first name. Enables personalized messaging using macros, such as {{firstname}}, in offer creatives (e.g., "John, your reward is waiting!"). |
zipcode | The userβs ZIP/postal code. Used to enhance geo-targeting accuracy beyond IP-based location detection. |
mobile | The userβs mobile phone number. Optional field for offer personalization or SMS-based promotions. Ensure compliance with privacy policies when using this attribute. |
confirmationref | A transaction or confirmation reference ID. This value can be used to personalize offer units (e.g., order summaries) and for downstream attribution in analytics. Example: confirmationref: "ORD-8931-AZQ" |
country | The user's country, in ISO 3166-1 alpha-2 format. Useful for geographic targeting when IP location data is not reliable. Example: country: "US" |
adpx_fp | A unique user fingerprint used for frequency capping, impression tracking, and audience segmentation. This should be a persistent, anonymized identifier, such as a hashed user ID or device ID. |
Example Usages for Payload Attributes
Payload attributes unlock advanced functionality such as user identification, traffic source tracking, and personalized experiences. Below are common use cases with implementation examples.
Tracking the Source of Offers
To analyze where your offers are shown or clicked, use the placement and/or subid attributes. These values can be anything meaningful to your tracking or analytics setup.
- placement: Indicates the page or screen (e.g., order_success)
- subid: Optional field used for affiliate-style tracking or campaign tagging
{
"placement": "account_rewards_page",
"subid": "email_promo_july"
}
Passing Contextual Information with tags
In addition to standard payloads, you can pass contextual hints using the tags attribute. This can help tailor which offers are rendered to the user based on preferences or segments.
- Accepts either a comma-separated string or an array of strings
- Useful for passing user interests, behavior tags, or session context
{
"tags": "gaming,frequent_buyer"
}
The tags attribute only applies to the following types of implementations:
- JS SDK (for Websites)
- Perkswall API
- Moments API
ο»Ώ
Supported Methods for Passing Payload Values
Payload attributes can be passed through different MomentScience integration methods, depending on your implementation. Below are supported methods and guidance on how to structure payloads for each.
Moments API
You can pass payload values using the Moments API by including them as key-value pairs in the JSON request body.
- These attributes help define context, enable personalization, and improve reporting.
- There is no hard limit to the number of attributes, but we recommend no more than 10 custom fields per request.
Perkswall API
Similar to the Moments API, the Perkswall API supports passing payload values as a JSON object in the request body.
- Attributes can include standard, reserved, or custom fields.
- Use this method to enrich user context for better offer relevance and segmentation.
Moments JS SDK (for Websites)
In web environments using the JS SDK, payload values are passed using the global window.AdpxUser object. This object must be defined before the SDK is initialized.
window.AdpxUser = {
email: "[email protected]",
firstname: "John",
zipcode: "74839",
theme_id: "momentscience_post_transaction",
country: "US",
adpx_fp: "df983hgjdl9023klasjd",
placement: "post_transaction",
loyalty_program_id: "23445665393"
};
Always initialize window.AdpxUser before loading the SDK script.
Direct Offer Links
For Direct Offer Links, append payload values as query parameters to the offer URL. This allows simple one-click tracking and personalization.
https://trk.pubtailer.com/sdk/offer-click?o_id=XXXX&c_id=XXX&p_id=XX&user_id=3a99022vv&order_id=402230000The same method to add payload values in Direct Offer Links can be used on click_url values returned in the Offer Catalog API response.
Perkswall Direct Offer Links
Perkswall supports Direct Offer Links in the same mannerβvia query parameters in the URL.
https://get.perkswall.com/offerwall?accountId=99e58babc94df55a&offer_count=9&auto_show=true&show_logo=true&show_header=true&show_shadow=false&show_image=true&o_id=3923&user_id=3a99022vv&order_id=402230000These values are accessible in reporting and can be returned in conversion postbacks.
If you encounter any issues or need support during integration, contact us at [email protected].