JavaScript SDK Guide

16 min

Who is this for: Web developers integrating MomentPerks using the JavaScript SDK for a low-code implementation on websites or online stores.

Outcome: Retrieve the SDK snippet from the dashboard, embed it on the target page, configure runtime options, and validate that offers are displaying correctly.

Overview

MomentPerks makes it easy to integrate personalized offers into your website, online store, mobile app, or other digital experiences. Using our JavaScript SDK, you can quickly start showing offers to users at the right time, such as after a purchase or during checkout.

This guide will walk you through how to:

Get your SDK snippet from the MomentScience dashboard

Add the SDK to your website

Configure runtime options

Pass user-specific data to personalize offers

Validate that your integration is working correctly

Requirements

Before you begin, ensure you have:

SDK ID: This is your unique identifier for MomentScience, You can find it in the MomentScience Dashboard under Profile Settings.

For detailed instructions on how to retrive your SDK ID, see Getting your SDK ID.

Integration Steps

To help you get started, the following interactive demo walks through the process of getting the JavaScript SDK code snippt from the dashboard.

The "SDK ID" is also referred to as the "Account ID" in the JavaScript snippet shown in the dashboard. These terms are interchangeable, they refer to the same value.

Step 1: Access Your Integration Code

To retrieve your JavaScript SDK integration code:

Go to the MomentScience dashboard.

From the left sidebar, click Integrations and select Moments.

You'll be redirected to the MomentPerks Integration page.

Click the Install Theme tab, or go directly to this link.

Your JavaScript SDK code will appear. You can copy it directly or download it for later use.

Step 2: Add the SDK to Your Website

Paste the integration code before the closing </head> tag of your site.

Ensure your accountIdvalue in your script matches your SDK IDSDK ID from the MomentScience dashboard.

<script type="module">
  (function (window) {
    window.AdpxConfig = {
      accountId: 'YOUR_SDK_ID', // Replace with your account's SDK ID
      autoShow: true
    };

    window.AdpxUser = {
      // Optional: Define user-specific values
    };
  })(window.self !== window.top ? window.top : window);

  (async function (window) {
    const target = window.document.head || window.document.body;
    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.src = 'https://cdn.pubtailer.com/launcher.min.js';
    script.crossOrigin = 'anonymous';
    script.async = true;
    script.id = 'adpx-launcher';
    target.appendChild(script);

    await new Promise((resolve) => {
      window.Adpx
        ? resolve()
        : script.addEventListener('load', resolve);
    });

    window.Adpx.init(window.AdpxConfig);
  })(window.self !== window.top ? window.top : window);
</script>

Pinning the SDK to a Version (Optional)

These options apply to the SDK v2 script, launcher.latest.js. By default, your page loads the latest SDK release, so you get fixes and improvements without changing anything. If your page needs a script that never changes without your involvement, load a version-pinned file instead. This suits pages where an unannounced change would be costly, such as an order confirmation page, or a tag manager setup where tag changes skip your normal code review.

Option	Script URL	What you get
Auto-updating (default)	https://sdk-js.pubtailer.com/launcher.latest.js	Always the current release. No action needed to receive fixes.
Version-pinned	https://sdk-js.pubtailer.com/launcher.2.0.0.js	Always that exact version. You upgrade on your own schedule.

To pin, replace launcher.latest.js in your script tag with launcher. followed by the version number and .js:

<script src="https://sdk-js.pubtailer.com/launcher.2.0.0.js"></script>

How pinned versions behave:

A pinned file is never changed after release. Fixes ship as a new version number, never by replacing an existing file.

A version number that was never released returns a not-found error. It never falls back to another version.

Pinned files don't receive fixes. To pick up a newer release, change the version number in your script tag and test the page before you publish.

Not sure which version to pin? Contact your account manager or [email protected] for the current release number.

Step 3: Configure SDK Initialization

The SDK uses window.AdpxConfig to configure Offer behavior at runtime. You must set this configuration before the SDK script is loaded on the page.

The table below explains all supported attributes for Adpx.init():

Parameter	Type	Required	Description	Default
accountId	String	Yes	Your unique MomentScience account identifier. Also referred to as the SDK ID. The SDK uses this value to associate offer delivery, analytics, and creative rendering with your account. Learn how to fetch your SDK IDLearn how to fetch your SDK ID	—
autoLoad	Boolean	No	Controls whether the SDK automatically fetches offers when initialized. true: the SDK loads Offers automatically once initialized. false:you must manually trigger Offer loading by calling window.Adpx.refresh(). This is useful if you want to delay offer fetching until after a specific user action or event. For more information refer to Customize Offer Unit Timing documentation.	true
autoShow	Boolean	No	Controls whether offers are automatically displayed after being fetched true:Offers will appear automatically once fetched. false: you must explicitly call window.Adpx.show() to display Offers. Note: If autoLoadis set to false, autoShowhas no effect and will be ignored. For more information refer to Customize Offer Unit Timing documentation.	true
prefetch	Boolean	No	Enables offer prefetching for faster performance and smoother experiences. When set to true: Fetches and stores offers in localStorage during the first page load. Reuses the same offers and session ID on subsequent page loads within 1 hour. Maintains the selected state across page reloads when User Selected PerksUser Selected Perks (USP) (USP) is enabled. Avoids an extra network request on second load by using cached data. Cache expiration rules: Valid for 2 page views or 1 hour, whichever comes first. After expiration or the third load, the SDK fetches new offers and generates a new session ID.	false
dev	Boolean	No	Enables developer testing mode. When set to true: The SDK fetches offers in a developer-safe environment. No engagement or impression data is recorded. Geo-targeting is disabled. Returns all possible offers, ignoring targeting rules. Recommended when validating payloads, testing integration, or debugging issues.	false
theme_id	String	No	ID of the theme to render, copied from Theme Customizer. When set, it takes priority over the theme picked by your placement. See Managing Multiple Themes.
settings	Object	No	Allows you to override MomentScience Dashboard settings at runtime. Common use cases: Force a specific placement (e.g., "post_transaction") Apply a custom theme per page Adjust unit behavior for certain views For more information refer to Overriding Offer Unit Settings documentation	{}
styles	Object	No	Enables custom styling of the Moments unit at runtime. Supported customization areas include: Unit layout and spacing Header appearance (background, text) Content font styles and sizes Primary CTA (positive button) styling Secondary CTA (negative button) styling Body font and colors Footer content and style For more information refer to Overriding Offer Unit Styles documentation	{}

window.AdpxConfig = {
  accountId: 'YOUR_SDK_ID',
  autoLoad: true,
  autoShow: true,
  dev: true,
  settings: {},
  styles: {}
};

Step 4: Pass in User Data (Recommended)

You can optionally provide user-specific payload values using the window.AdpxUserobject. This allows MomentScience to personalize Offer content, improve targeting, and enhance reporting.

User data must be defined before the SDK initialization (window.Adpx.init()), and can be set from either the client side or injected server-side at page render.

For detailed information about passing payload values using the JS SDK, refer to Passing Payload Values

Why Pass User Data?

Use Case	Benefit
Personalization	Show offers relevant to each user
Better Targeting	Deliver Offers based on specific user attributes like geography, membership status, or custom segments.
Improved Reporting	Track engagement by user or segment
Loyalty Support	Enable reward-based experiences for users who engage with partner Offers using provided IDs.

Example Payload Data

You can include any custom key-value pairs, but the following are commonly used:

Key	Example	Description
placement	'post_transaction'	Context in which the Offer appears (e.g., 'checkout', 'thank_you').
pub_user_id	'user-abc-123'	Unique identifier for the user from your system.
firstname	'John'	User’s first name. Used in personalized messages.
zipcode	'74839'	Helps geo-target specific Offers.
country	'US'	Country code (ISO 3166-1 alpha-2).
adpx_fp	'df983hgjdl9023klasjd'	Adpx fingerprint or tracking token.
Custom Fields	'plan': 'gold'	Add any extra targeting or analytics attributes as needed.

window.AdpxUser = {
  placement: 'post_transaction',
  pub_user_id: `UniquePubUserID`,
  firstname: 'John',
  zipcode: '74839',
  country: 'US',
  adpx_fp: 'df983hgjdl9023klasjd',
  loyalty_program_id: '23445665393',
};

Step 5: Verify Your Integration

Once you've added the SDK:

Open a page where the SDK is installed.

Complete an action where an offer should display (e.g., after checkout).

Open your browser’s Developer Tools → Console and confirm:

window.Adpx exists

window.AdpxUser shows the correct payload values

If offers do not appear, make sure your accountId is correct and check for errors in the console.

Next Steps

Now that you’ve set up the JavaScript SDK, the next step is to choose how offers are displayed to your users. MomentScience provides multiple presentation options, including modal popups, multi-offer layouts, and embedded units so you can match the experience to your website’s design.

For implementation details and customization guidance, see the Presentation OptionsPresentation Options documentation.

If you have any issues or questions, contact us at [email protected]