Passing Payload Values

21min

Introduction
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. Using payload values improves personalization, targeting, reporting, and integration efficiency.
Main Uses for Payloads

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: Pass payload values to attribute your implementations, generate reports that segment performance, and gain deeper insights into business outcomes.
Supporting LoyaltyBoost Offers: Payload values facilitate rewarding users for engaging with partners through LoyaltyBoost Offers.
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
﻿
Passing Payload Values
Reserved Attributes
MomentScience allows passing any ad-hoc key-value pairs in the payload, but some attributes have predefined meanings and should be used accordingly to avoid unintended behavior. These reserved attributes serve specific roles within the MomentScience system:
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:
﻿Perkswall API - V1﻿﻿
﻿Moments API﻿﻿
ua
The User-Agent of the end-user.
Only used as a reserved attribute for the following implementation methods:
﻿Perkswall API - V1﻿﻿
﻿Moments API﻿﻿
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:
﻿Perkswall API - V1﻿﻿
﻿Moments API﻿﻿
﻿JS SDK (for Websites)﻿﻿
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.
Custom Key-Value Attributes
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.
Custom key-value payloads provide two key advantages:
Real-time notifications using Conversion Postbacks to synchronize data immediately.
Advanced custom reporting to analyze performance across multiple dimensions.
Example:
Passing Custom Key-Value Attributes
  membershipID: "A45GRE987343PKD",
  source: "email",
  interests: "gardening"
  membershipID: "A45GRE987343PKD",
  source: "email",
  interests: "gardening"
﻿
Recommended Attributes
Attribute
Description
email
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.
﻿
Example Usages for Payload Attributes
Identifying Unique Users 
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.
Example Using JS SDK
Example Using Moments and Perkswall API
Direct Offer Links
Perkswall Direct Offer Links
    window.AdpxUser = {
        // Other Payload attributes
        adpx_fp: "REPLACE_WITH_YOUR_VALUE"
    };
    window.AdpxUser = {
        // Other Payload attributes
        adpx_fp: "REPLACE_WITH_YOUR_VALUE"
    };
﻿
Determining the Source of Your MomentScience Offers
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.
Example Using JS SDK
Example Using Moments and Perkswall API
Direct Offer Links
Perkswall Direct Offer Links
https://get.perkswall.com/offerwall?accountId=f0f16460-f739-4ec0-b220-b31745a78b3b&o_id=3923&subid=moments_offer_unit&placement=post_transaction
https://get.perkswall.com/offerwall?accountId=f0f16460-f739-4ec0-b220-b31745a78b3b&o_id=3923&subid=moments_offer_unit&placement=post_transaction
﻿


Passing Contextual Information
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:
﻿JS SDK (for Websites)﻿﻿
﻿Perkswall API - V1﻿﻿
﻿Moments API﻿﻿
﻿
Supported Methods for Passing Payload Values
Moments API
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.
Checkout Moments API Documentation
﻿
Perkswall API
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.
Checkout Perkswall API Documentation  
﻿
Moments JS SDK
Payload values are specified within the properties of the window.AdpxUser object.
Setting init Attributes
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'
};
window.AdpxUser = {
  email: 'user@domain.com', 
  firstname: 'john',
  zipcode: '74839',
  theme_id: 'momentscience_post_transaction',
  country: 'US',
  adpx_fp: 'df983hgjdl9023klasjd',
  placement: 'post_transaction',
  loyalty_program_id: '23445665393'
};
﻿
Checkout JS SDK Documentation
﻿
Direct Offer Links
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:
https://trk.pubtailer.com/sdk/offer-click?o_id=XXXX&c_id=XXX&p_id=XX&user_id=3a99022vv&order_id=402230000
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.
Checkout Direct Offers Documentation
﻿
Perkswall Direct Offer Links
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:
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=402230000
Checkout Perkswall Direct Offers Documentation
﻿
﻿
📢 If you're running into any issues while going through the integration process, feel free to contact us at [email protected] 

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: Perkswall API - V1 Moments API
ua	The User-Agent of the end-user. Only used as a reserved attribute for the following implementation methods: Perkswall API - V1 Moments API
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: Perkswall API - V1 Moments API JS SDK (for Websites)
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.

Attribute	Description
email	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.

Updated 21 Jan 2025

Did this page help you?

Email Reports

Handling Postback Events