---
title: JavaScript SDK Guide
slug: javascript-sdk-guide
icon: {"faIcon":"fa-solid fa-code"}
docTags: 
createdAt: 2025-07-24T14:50:56.465Z
---

:::hint{type="info"}
**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](https://app.momentscience.com) under [Profile Settings.](https://app.momentscience.com/account/profile-settings)

:::hint{type="success"}
For detailed instructions on how to retrive your SDK ID, see [Getting your SDK ID](docId\:cjrqr7fQDkYbwzuDXxZa9).
:::

***

# 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.

:::Iframe{iframeHeight="0" code="<div style=&#x22;position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.517263025737602; padding: 40px 0 40px 0;&#x22;><iframe src=&#x22;https://play.momentscience.com/embed/cmdnj2csf08409f964x01157e?embed_v=2&utm_source=embed&#x22; loading=&#x22;lazy&#x22; title=&#x22;JavaScript SDK Guide [Getting JS Code Snippet]&#x22; allow=&#x22;clipboard-write&#x22; frameborder=&#x22;0&#x22; webkitallowfullscreen=&#x22;true&#x22; mozallowfullscreen=&#x22;true&#x22; allowfullscreen style=&#x22;position: absolute; top: 0; left: 0; width: 100%; height: 100%;&#x22;></iframe></div>"}

:::

:::hint{type="info"}
The "SDK ID" is also referred to as the "Account ID" in the JavaScript snippet shown in the [dashboard](https://app.momentscience.com). These terms are interchangeable, they refer to the same value.
:::

## Step 1: Access Your Integration Code&#x20;

To retrieve your JavaScript SDK integration code:

1. Go to the [MomentScience dashboard](https://app.momentscience.com/home).
2. From the left sidebar, click **Integrations** and select **Moments**.
3. You'll be redirected to the [MomentPerks Integration](https://app.momentscience.com/account/integration/customize#customize) page.
4. Click the **Install Theme** tab, or [go directly to this link](https://app.momentscience.com/account/integration/customize#install).
5. 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

1. Paste the integration code **before the closing&#x20;**`</head>`**&#x20;tag&#x20;**&#x6F;f your site.
2. Ensure your `accountId`value in your script matches your [SDK ID](docId\:cjrqr7fQDkYbwzuDXxZa9) from the MomentScience dashboard.&#x20;

:::CodeblockTabs
Example JavaScript Snippet

```javascript
<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>

```
:::

## Step 3: Configure SDK Initialization

The SDK uses `window.AdpxConfig` to configure Offer behavior at runtime. You **must&#x20;**&#x73;et 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&#x20;** |
| ------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `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.<br />[Learn how to fetch your SDK ID](docId\:cjrqr7fQDkYbwzuDXxZa9)                                                                                                                                                                                                                                                                                                                                                                                                                        | —                 |
| `autoLoad`    | Boolean  | No           | Controls whether the SDK **automatically fetches offers&#x20;**&#x77;hen initialized.<br />* `true`: the SDK loads Offers automatically once initialized.
* `false`:you must manually trigger Offer loading by calling `window.Adpx.refresh()`.<br />This is useful if you want to delay offer fetching until after a specific user action or event.<br /><br />For more information refer to [Customize Offer Unit Timing documentation.](docId:-LFsS4N-fV4dXSKXSJ24o)                                                                                                                                                                                                            | `true`            |
| `autoShow`    | Boolean  | No           | Controls whether offers are **automatically displayed&#x20;**&#x61;fter being fetched <br />* `true`:Offers will appear automatically once fetched.
* `false`: you must explicitly call `window.Adpx.show()` to display Offers.<br />**Note:&#x20;**&#x49;f `autoLoad`is set to `false`, `autoShow`has no effect and will be ignored.<br /><br />For more information refer to [Customize Offer Unit Timing documentation.](docId:-LFsS4N-fV4dXSKXSJ24o)                                                                                                                                                                                                                           | `true`            |
| `prefetch`    | Boolean  | No           | Enables **offer prefetching&#x20;**&#x66;or faster performance and smoother experiences. When set to `true`: <br />* 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 Perks](docId\:MCK87it11JXVj9KYC_543) (USP) is enabled.
* Avoids an extra network request on second load by using cached data.<br />**Cache expiration rules:** <br />* 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`:<br />* 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.&#xA;<br />Recommended when validating payloads, testing integration, or debugging issues.                                                                                                                                                                                                                                                                                                                                 | `false`           |
| `settings`    | Object   | No           | Allows you to override MomentScience Dashboard settings at runtime. Common use cases:<br />* Force a specific placement (e.g., "`post_transaction`")
* Apply a custom theme per page
* Adjust unit behavior for certain views<br /><br />For more information refer to [Overriding Offer Unit Settings documentation](docId\:bCirtahUsXtymPlXD4mgJ)                                                                                                                                                                                                                                                                                                                                | `{}`              |
| `styles`      | Object   | No           | Enables custom styling of the Moments unit at runtime. Supported customization areas include:<br />* 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<br /><br />For more information refer to [Overriding Offer Unit Styles documentation](docId\:bCirtahUsXtymPlXD4mgJ)                                                                                                                                                                                                                        | `{}`              |

:::CodeblockTabs
Example Configuration

```javascript
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.AdpxUser`object. 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.

:::hint{type="success"}
For detailed information about passing payload values using the JS SDK, refer to [Passing Payload Values](docId\:yZ38zu4_miummWTnnsG98)&#x20;
:::

### 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.              |

:::CodeblockTabs
Example Payload Data

```javascript
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:

1. Open a page where the SDK is installed.
2. Complete an action where an offer should display (e.g., after checkout).
3. Open your browser’s **Developer Tools** → **Console** and confirm:
   - window\.Adpx exists
   - window\.AdpxUser shows the correct payload values
4. 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 Options](docId:9UkjGFQBK0fvD1Qahw51L)     documentation.

***

If you have any issues or questions, contact us at [help@momentscience.com](mailto\:help@momentscience.com)