Customize Offer Unit Timing
Who is this for: Developers using the MomentPerks JavaScript SDK who need to control exactly when offers are fetched and displayed in single-page applications or multi-step flows.
Outcome: Configure autoLoad and autoShow options-and use refresh() and reload()-to precisely control offer timing based on user context or application state.
Overview
By default, the MomentScience JavaScript SDK automatically fetches and displays the Moments Offer Unit when initialized. This behavior is controlled using two configuration options: autoLoadand autoShow.
You can modify these options to delay when offers are fetched or shown, for example, in single-page applications or multi-step checkout flows where user data isnβt immediately available.
This guide explains how to:
- Configure autoLoadto delay fetching Offers
- Configure autoShowto delay displaying the Offer Unit
- Use refresh() to fetch a new set of Offers
- Use reload() to redisplay a previously fetched Offer Unit
- Understand how different configuration combinations affect SDK behavior
Default behavior
If no configuration changes are made:
- Offers are fetched automatically when the SDK loads (autoLoad: true).
- Offers are displayed immediately after being fetched (autoShow: true).
This behavior is suitable for most use cases, especially when no conditional logic is required to determine when offers appear.
flowchart TD
A[SDK Initialization] --> B{autoLoad?}
B -- Yes --> C[Fetch Offers Automatically]
B -- No --> D[Wait for Adpx.refresh]
C --> E{autoShow?}
D --> F{autoShow?}
E -- Yes --> G[Display Offers Automatically]
E -- No --> H[Wait for Adpx.reload]
F -- Yes --> G
F -- No --> H
G --> I[User Closes Offer Unit]
I --> J[User Reopens via Adpx.reload]
D --> K[Optional: setPayload before refresh]
%% Node styles
style A fill:#233D71,stroke:#233D71,stroke-width:2px,color:#ffffff
style B fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
style C fill:#3B82F6,stroke:#233D71,color:#ffffff
style D fill:#FE4215,stroke:#FE4215,color:#ffffff
style E fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
style F fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
style G fill:#3B82F6,stroke:#233D71,color:#ffffff
style H fill:#FE4215,stroke:#FE4215,color:#ffffff
style I fill:#F9F9F9,stroke:#6E6D7A,color:#6E6D7A
style J fill:#3B82F6,stroke:#233D71,color:#ffffff
style K fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49Controlling Display Behavior
To take control over when offers are retrieved or shown, use the autoLoadand autoShowconfiguration options.
Delay Fetching Offers (autoLoad )
To delay the initial API call for fetching offers, set autoLoadto falsein your configuration object:
window.AdpxConfig = {
accountId: 'YOUR_SDK_ID',
autoLoad: false
};With autoLoad: false, the SDK will not request offers when initialized. Instead, you must manually trigger the fetch using window.Adpx.refresh().
Manually Fetching Offers (refresh())
To retrieve offers at a specific time, call the refresh() method, this allows you to:
- Fetch new offers based on updated session or user state
- Control when offers are retrieved within your app flow
window.Adpx.refresh();If youβve updated the payload, make sure to call setPayload() before refresh() so the new data is included in the request.
Updating the Payload (setPayload())
UsesetPayload() to define or update the values passed to the offer API. This is especially useful in scenarios where user context or transaction data changes before fetching offers.
window.Adpx.setPayload({
user_id: '1234',
category: 'electronics'
});
window.Adpx.refresh();Preventing Automatic Display (autoShow )
By default, offers are displayed immediately after theyβre fetched. To delay this behavior, set autoShowto false:
window.AdpxConfig = {
accountId: 'YOUR_SDK_ID',
autoLoad: true,
autoShow: false
};
With autoShow: false, offers will be fetched but not shown automatically. You must explicitly call reload() to display the Offer Unit.
Manually Display Offers(reload())
Use the reload() function to show the Offers Unit after offers have been fetched:
window.Adpx.reload();This displays the current set of fetched offers. Itβs useful when:
- A user previously closed the Offers Unit
- You want to re-display existing offers without re-fetching them
reload() does not fetch new offers. Use refresh() for that purpose.
Combined Configuration Scenarios
This table summarizes how the SDK behaves under different autoLoad and autoShow settings:
autoLoad | autoShow | SDK behavior |
|---|---|---|
true | true | Offers are fetched and displayed automatically. (Default) |
false | true | Offers must be fetched manually using refresh(). Once fetched, the Offer Unit appears automatically. |
false | false | Offers must be fetched manually using refresh(), and displayed manually using reload(). |
true | false | Offers are fetched automatically, but you must call reload() to display them. |
Re-Displaying and Re-Fetching Offers
Redisplaying Previously Fetched Offers (reload())
Use the reload() method to redisplay the current set of Offers without making a new request to the backend.
window.Adpx.reload();This is helpful in cases where:
- A user previously dismissed the Moments Offer Unit and wants to see the Offers again
- You want to show the same Offers on a new screen or state change in your app
reload() does not fetch new Offers. It redisplays the last fetched set, starting from the first Offer.
Fetching a New Set of Offers (refresh())
To fetch a new set of Offers, especially after user data or app context has changed, use the refresh() method:
window.Adpx.refresh();If the payload has changed (e.g., new user_id, category, or location), call setPayload() before calling refresh():
window.Adpx.setPayload({
user_id: '5678',
category: 'home-goods'
});
window.Adpx.refresh();
Use this method when:
- New user attributes should influence the Offers shown
- Offers should reflect updated application context or session state
- You want to dynamically rotate the content of the Offer Unit
If you're running into any issues while going through the integration process, feel free to contact us at help@momentscience.comο»Ώ