Customization Options

20 min

Who is this for: Web developers who need to extend or override the default MomentPerks JavaScript SDK behavior through callbacks, styling overrides, and runtime configuration.

Outcome: Register lifecycle callback functions, override visual styles, and control offer display timing programmatically to create a tailored, responsive offer experience.

Overview

This guide shows how to customize the MomentScience JavaScript SDK to match your product experience. You can control when offers appear, override styles, and subscribe to offer lifecycle events.

With the JS SDK, you can:

Track offer lifecycle events using callback functions.

Customize the layout, colors, fonts, and buttons.

Override default settings dynamically in code.

Control when offers are fetched and displayed.

If you want to edit the visual appearance of the Offer Unit without changing code, use the Visual Theme Customizer. Refer to the Theme Customizer for step-by-step instructions.

Callback functions

The MomentScience JavaScript SDK allows you to register callback functions that trigger during key offer lifecycle events. These callbacks let your code respond in real time whenever a user interacts with an offer. For example, you can:

Track analytics: Log when a user claims or skips an offer.

Update the UI: Show custom messages, animations, or surveys.

Trigger other actions: Redirect users, enable features, or adjust other elements based on user behavior.

Callbacks are essential for creating a dynamic and responsive user experience, because they provide immediate access to each offer’s event data.

Passing a Callback Function

To register a callback, pass a function as the second parameter to window.Adpx.init(). This function will be invoked whenever the SDK emits an event.

You can use this to trigger additional behavior, such as showing a survey, logging user behavior, or adjusting the UI, based on offer interactions.

Supported Events

The following events are fired by the JavaScript SDK during the offer lifecycle. You can use them to track user interactions and trigger custom behaviors.

Event	Description	Payload fields
ads_found	Offers were found and returned by the SDK.	total (integer): Total number of offers returned
no_ads_found	No relevant offers were returned. No further events will be triggered. after this event.	No payload for this event
ad_taken	User clicked the positive CTA (e.g. Claim Now) and the offer opened in a new browser tab.	target_url (string): Destination URL for the claimed offer total (integer): Total number of offers returned by the SDK. current (integer): Postion of current Offer in the list of Offers presented
ad_not_taken	User clicked the negative CTA (e.g. No Thanks).	total (integer): Total number of offers returned by the sdk current (integer): Position of current Offer in the list of Offers presented
closed_ads	Offer unit was closed or completed. Triggered when: The user clicks the close (×) icon The user clicks on the negative CTA button on the last Offer. The user clicks "More Offers" when reaching the last Offer.	No payload for this event

Example Usage

window.Adpx.init(AdpxConfig, (event, payload) => {
  console.log('Received event from MomentScience SDK:', event, payload);

  if (event === 'closed_ads') {
    showMySurvey();
  }

  if (event === 'ad_taken') {
    console.log(`User took offer ${payload.current} of ${payload.total}`);
  }

  if (event === 'ad_not_taken') {
    console.log(`User passed on offer ${payload.current} of ${payload.total}`);
  }
});

Overriding Settings and Styles

You can control the Moments Offer Unit’s behavior and appearance by using the settings and styles parameters in your AdpxConfig object. This allows precise adjustments without changing the dashboard configuration.

Behavior (settings): Controls how the Offer Unit behaves and interacts with users:

When offers appear (immediate, delayed, or on exit intent)

Unit position on screen (desktop and mobile)

Button order and logic (positive/negative CTAs)

Multi-offer layout and navigation (MOU vs SOU)

User Selected Perks (USP) checkboxes

Appearance (styles): Controls visual elements of the Offer Unit:

Fonts, text sizes, and colors for headers, offer tiles, and CTAs

Popup container background, border radius, and shadows

Header and footer layout, text, and branding

Offer images, tile spacing, and offerwall styles

window.AdpxConfig = {
  accountId: 'YOUR_SDK_ID',
  autoShow: true,
  settings: {
    // Add custom behavior options here
  },
  styles: {
    // Add style overrides here
  }
};

Overriding Offer Unit Settings

You can customize the behavior of the Moments Offer Unit by adding a settings object inside window.AdpxConfig. These settings control how offers are displayed, interacted with, and organized.

Setting	Type	Description
ad_position	String	Defines the placement of the Offer Unit on the screen for desktop environments. The default position is center. Available values: center bottom-center bottom-left bottom-right top-center top-left top-right
darken_bg	Boolean	When true, adds a background overlay behind the Offer Unit for focused attention. Only works when ad_position is center.
darken_bg_non_centered	Boolean	Similar to darken_bg, but applies the background overlay when ad_positionis not center.
delay	Integer	Number of seconds to wait after fetching offers before displaying the Offer Unit. Useful for giving context or delaying display until key moments.
privacy_policy	String	Link to your Privacy Policy. If provided, it will be shown in the footer of the Offer Unit.
screen_margin	Integer	Pixel value for the margin between the Offer Unit and the browser window edges.
show_disclaimer	Boolean	If true, displays disclaimer text in the Offer Unit footer. You can configure the actual disclaimer text via the dashboard.
button_order	String	Controls which CTA button is shown first, available options are: neg_first: This will show the negative button first. pos_first: This will show the positive button first.
enable_vertical_offset	Boolean	When it's set to true, vertical adjustment is enabled for the Onit. Offers Unit. This means that the unit can be vertically repositioned on the screen. Used with screen_margin. When set to false, vertical adjustment is disabled, and the unit remains fixed in its default position.
mobile_vertical_offset	Integer	For mobile web, It specifies the pixel margin from the top of the container. Leaving this blank or entering 0 will cause the container to load at the center of the window.
no_of_ads	Integer	Sets the maximum number of offers displayed in the Offer Unit.
multi_offer_unit	Boolean	Determines whether the Offer Unit is displayed as a Multi Offer Unit (MOU) or the Standard Offer Unit (SOU). By default, it is set to false. true: renders the Offers as a multi-tile layout (Multi Offer Unit). false: displays the default single offer view (SOU). Learn more about Multi Offer Unit
show_multi_offer_unit	Boolean	Controls whether the multi offer layout is displayed at runtime. This setting only takes effect if multi_offer_unit is set to true. Use this toggle to conditionally render the multi-tile layout based on user behavior or feature flags.
show_ads_on_exit	Boolean	When enabled, the Offers Unit is triggered when a user intends to exit or close a page, based on tracked mouse movement. This feature is only applicable in Desktop Web environments.
close_ad_on_click_outside	Boolean	When this option is enabled, the user can close the Offer by clicking anywhere outside the ad. true: The Offer will close if the user clicks outside the ad. false:The Offer will remain open even if the user clicks outside it. This feature is only applicable in Desktop Web environments.
auto_close_enabled	Boolean	When true, the Offer Unit will automatically close after a set duration without any user interaction. Use in combination with auto_close_timer_minutes to define how long the unit remains open.
auto_close_timer_minutes	Integer	Number of minutes before the Offer Unit automatically closes. Only applies when auto_close_enabled is true.
ad_animation	String	By default, the animation is set to null. This attribute allows you to customize the entry animation of the Offers Unit with the following values: top-bottom bottom-top left-right right-left
show_close	Boolean	It determines whether to show or disable the Close Offer (X) button at the top right corner of the Offers Unit. true: The close button will be displayed. false: The close button will be hidden.
enable_close_delay	Boolean	When true, the close (X) button will not appear immediately. Requires close_delay.
close_delay	Integer	It allows you to add a delay before showing the Close Offer (X) button after displaying the Offers Unit. Only applicable when enable_close_delay is true. Recommended values are 1, 2,3,5, and 10
embedded	Object	An object that can contain the following : enabled: (Boolean) When true it will enable embedding the Offers unit into your webpage. fill_container: (Boolean) When true, the embedded unit will take up the full height of its parent container. showBorder: (Boolean) when true it will make the embedded unit borderless for a more native look. showHeader:(Boolean) When set to true it will show the header of the unit. showFooter: (Boolean) When set to true it will show the footer of the unit. targetElement:(String) Specifies the ID of the HTML tag, preferably a <div> tag, where the embedded unit will be injected. If this parameter is missing or set to null, MomentScience defaults to the value adpx. Learn more about Embedding the Offer Unit.
enable_effect_shimmer_pos_cta	Boolean	Determines whether to activate a shimmer effect specifically on the positive call-to-action (CTA). When set to true, the shimmer effect will be enabled, providing a visually appealing animation to highlight the positive CTA button.
enable_offerwall	Boolean	Determine whether to enable the offerwall. If set to false, none of the offerwall-related settings will be operational.
fixed_progress_bar	Boolean	Determine if a fixed progress bar should be used on the Offers Unit. Turning this on will show a Progress Bar on the Offers Unit with the ability to view the next and previous Offers.
open_offerwall	Boolean	Determine whether to open the Perkswall in a new tab after clicking on the close button.
open_overlay_offerwall	Boolean	Determine whether to open Perskwall as an overlay within the Offers Unit.
offerText	Object	Defines the styling attributes for text elements within the offer unit, contains the following: font: (String) The font family for all text in the offer unit. Must be a valid Google Fonts font name. Enter the font name exactly as it appears (e.g., "Roboto Slab"), including spaces if any. textColor: (String) Hex code representing the text color. tileTextAlignment: (String) Controls horizontal alignment of text within the offer tile. Accepted values: "left" or "right". buttonRadius: (String) Sets the border radius (in pixels) of the button inside the offer unit. fontSizeTitle: (String) Sets the font size (in pixels) of the offer title. fontSizeDescription: (String) Sets the font size (in pixels) of the offer description text.
enable_usp	Boolean	Enables the User Selected Perks (USP) feature for the Offer Unit. When true, the Offers Unit displays checkboxes allowing users to select specific offers. Learn more about User Selected Perks
usp_all_offers_checked	Boolean	Determines whether all available offers should be pre-selected (checkboxes checked) when the Offer Unit loads. This setting is only applicable when enable_uspis true. Learn more about User Selected Perks (USP)
usp_cta_text	String	Custom text displayed next to the checkbox for each offer. This string appears only if enable_usp is enabled. Learn more about User Selected Perks
progress_bar_type	String	Defines the visual style of the offer navigation indicator. Accepted values: dots: Displays a simple dot for each offer (e.g., ● ● ●). Use this to match your desired UX or brand style. numbers: Displays the step number for each offer (e.g., ① ② ③).
enable_perkswallet	Boolean	Enables the PerksWalletPerksWallet feature for the selected theme. When set to true, a “Save for later” call-to-action (CTA) is displayed below the main offer button, allowing users to save offers to their PerksWallet for future use. Learn more about PerksWallet.
perkswallet_show_cta	Boolean	Controls the visibility of the “Save for later” CTA. If true, the CTA will be shown when enable_perkswalletis enabled. Learn more about PerksWallet.
saved_offer_text	String	Sets the custom text for the “Save for later” CTA button (e.g., “Save for later”, “Add to Wallet”).
perkswallet_cta	String	Defines the confirmation message shown after a user clicks the PerksWallet CTA (e.g., “Offer saved!”). Learn more about PerksWallet.

Overriding Offer Unit Styles

You can customize the appearance of the Moments Offer Unit by passing a stylesobject inside your AdpxConfig. This allows you to control fonts, colors, spacing, borders, and more, to match your product's visual design.

styles.popup

Use this section to control the appearance of the main Offer Unit popup container.

Property	Type	Description
background	String	Background color of the popup container (e.g., #ffffff).
borderRadius	Object	Controls corner radius for the popup. Accepts keys: top_left, top_right, bottom_left, bottom_right. Values are strings representing pixels (e.g., "5").
shadow	String	Hex color code for the box shadow applied around the popup (e.g., #000000).
lightBox	String	Background color for the lightbox effect behind the popup (e.g., #000).
image_position	String	Position of the image inside the offer layout. Accepts: left or right.
showImage	Boolean	Whether to display the image associated with each offer.

styles:{
   //Customize the Offers Unit Container
    popup: {
      background: "#ffffff",
      borderRadius: {
        bottom_left: "12",
        bottom_right: "12",
        top_left: "12",
        top_right: "12"
      },
      shadow: "#8f8f8f",
      lightBox: "#000",
      image_position: "left",
      showImage: true
    }
}

styles.header

Use this section to customize the header portion of the Offers Unit.

Property	Type	Description
text	String	Main header message displayed at the top of the Offers Unit (e.g., "Your order is complete").
background	String	Background color of the header section (e.g., #1A56DB).
textColor	String	Color of the header text (e.g., #fff).
fontSize	Integer	Size of the header text (e.g., 16).
headLineAndLeadInFontSize	Integer	Font size used for both headline and lead-in text (e.g., 14).
lead_in_text	String	Additional introductory text shown under the main header (e.g., "Here are some offers from brands you love!").
lead_in_text_color	String	Color of the lead-in text (e.g., #000000).
heading_font_size	String	Font size of the header text using a CSS value (e.g., "14px").
lead_in_alignment	String	Horizontal alignment of the lead-in text. Accepts: "start", "center", or "end".

styles:{   
    // Customize the Offers Header
    header: {
      background: "#0b1937",
      fontSize: 16,
      lead_in_text: "Here's something we think you'd love!",
      lead_in_text_color: "#477ba5",
      headLineAndLeadInFontSize: 15,
      text: "Your order is complete",
      textColor: "#fff"
    },
}

styles.offerText

This section customizes the text, fonts, and CTA buttons within each offer tile.

Property	Type	Description
cta_text_size	String	Font size of the call-to-action (CTA) text (e.g., "13px").
cta_text_style	String	CSS style applied to the CTA text. Accepts values like "normal", "italic", etc.
hide_adv_name	Boolean	When set to true, the advertiser’s name will not be shown inside the offer tile.
textColor	String	Hex color code for general text content (e.g., "#000").
font	String	Font family for all offer text (must be a valid Google Fonts name, e.g., "Roboto").
fontSize	Integer	Font size used for the offer description text (e.g., 13).
buttonYes	Object	Styling for the positive CTA button (e.g., "Claim Offer").Includes: background(hex) hover(hex) stroke(hex) color(hex)
buttonNo	Object	Styling for the negative CTA button (e.g., "No Thanks").Includes: background(hex) hover(hex) stroke(hex) color(hex)
offerwall_mou_button_radius	Integer	Border radius (in pixels) for buttons shown in the Offerwall or Multi Offer Unit.
show_image	Boolean	If true, the image for each offer tile will be shown; if false, it will be hidden.

styles:{
    // Customize the Offers Unit content
    offerText: {
      buttonNo: {
        background: "#fff",
        color: "#6B7280",
        hover: "#E5E7EB",
        stroke: "#9CA3AF"
      },
      buttonYes: {
        background: "#000000",
        color: "#fff",
        hover: "#0b1937",
        stroke: "#0b1937"
      },
      font: "Roboto",
      fontSize: 14,
      textColor: "#000",
      offerwall_mou_button_radius: 5,
      show_image: true
    },
}

styles.footer

This section controls the footer area of the Offers Unit, including legal links and publisher branding.

Property	Type	Description
disclaimer	String	Text displayed at the bottom of the unit to clarify terms (e.g., "External link. Clicking an offer will take you to the advertiser's website...").
text	String	Footer message text, usually a credit or branding note (e.g., "Powered by MomentScience").
publisher_privacy_policy	String or null	Custom URL to the publisher's privacy policy. Overrides the default MomentScience privacy link if set.
publisher_name	String	Name of the publisher to display in the footer.

styles:{
  // Customize the Offers Footer content
  footer: {
      disclaimer: "",
      publisher_name: "MomentScience Publisher",
      publisher_privacy_policy: null,
      text: "Powered by MomentScience"
  }
}

styles.offerwall

Customize the appearance of the Offerwall including tile layout and button styling for the Multi Offer Unit (MOU).

All color values must be provided as valid hex codes (e.g., #ffffff for white or #000000 for black).

Parent Key	Property	Type	Description
offerwall.button	offerwall_mou_button_background	String	Background color of the Perkswall button
	offerwall_mou_button_color	String	Text color used inside the Perkswall button
	offerwall_mou_button_hover	String	Background color shown when hovering over the button.
	offerwall_mou_button_stroke	String	Border (stroke) color of the Offerwall button.
offerwall.tile	offerwall_mou_border_color	String	Border color for each Offerwall tile.
	offerwall_mou_border_thickness	Integer	Thickness of the tile border in pixels.
	offerwall_mou_tile_background_hover_color	String	Background color of the tile on hover.
	mou_tile_background_color	String	Default background color of each tile.
offerwall	tile_radius	Integer	Corner radius of each tile in pixels.
	mou_tile_gap	Integer	Space (in pixels) between multi offer unit tiles

styles:{
   offerwall: {
      button: {
          offerwall_mou_button_background: "#FFF",
          offerwall_mou_button_color: "#6B7280",
          offerwall_mou_button_hover: "#E5E7EB",
          offerwall_mou_button_stroke: "#9CA3AF"
      },
      tile: {
          offerwall_mou_border_color: null,
          offerwall_mou_border_thickness: null,
          offerwall_mou_tile_background_hover_color: null
      },
      tile_radius: 4
   }
}

Next Steps

After reviewing SDK customization options, follow these guides to complete your integration:

1. Customize offer unit timing

Control when offers are fetched and displayed. Use setPayload(), refresh(), and reload() to manage dynamic offer behavior. Customize Offer Unit Timing

2. Manage multiple visual themes

Create, update, and apply visual themes to match your product design. Pass theme_id in SDK or API integrations for dynamic rendering. Managing Multiple Themes

3. Validate your integration

Confirm offers appear at intended points in your app flow.

Verify the correct theme is applied.

Test dynamic updates to ensure payload and configuration changes are reflected.

If you're running into any issues while going through the integration process, feel free to contact us at help@momentscience.com