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 must be consistent across sessions and devices do not use personally identifiable information (pii) such as emails or phone numbers can be generated using any logic as long as it remains unique per 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 https //en wikipedia org/wiki/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, and yield optimization it should be a stable, non pii string (e g , hashed id, uuid) that remains consistent across user sessions for mobile apps when user consent is present, use the device's advertising identifier (idfa on ios, gaid on android) as the adpx fp value 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 perkswall api moments api ua the user agent string from the end user's browser or device this is useful for advanced targeting and is only supported by perkswall api moments api 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 moments api perkswall api js sdk (for websites) 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 passing custom key value attributes 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 email 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 https //en wikipedia org/wiki/iso 3166 1 alpha 2 useful for geographic targeting when ip location data is not reliable example country "us" adpx fp a unique user fingerprint used for frequency capping and impression tracking this should be a persistent, anonymized identifier, such as a hashed user id or device id for mobile apps when user consent is present, use the device's advertising identifier (idfa on ios, gaid on android) as the adpx fp value 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 js sdk window\ adpxuser = { placement "post transaction", subid "offer test group 1" }; api request body { "placement" "account rewards page", "subid" "email promo july" } direct offer link https //trk pubtailer com/sdk/offer click?o id=1234\&placement=confirmation page\&subid=email promo julyhttps //get perkswall com/offerwall?accountid=xyz789\&o id=3923\&placement=checkout done\&subid=affiliate 21 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 window\ adpxuser = { tags \["fitness", "loyalty user", "high value"] }; perkswall or momentperks api request boby { "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 passing payload values using js sdk window\ adpxuser = { email "user\@example com", 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 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 perkswall direct offer links perkswall supports direct offer links in the same manner—via query parameters in the url 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 these 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 mailto\ help\@momentscience com