--- title: Customization Options slug: customization-options icon: 🎨 docTags: createdAt: 2025-07-24T15:09:19.692Z --- :::hint{type="info"} **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. :::hint{type="info"} If you want to edit the visual appearance of the Offer Unit without changing code, use the [Visual Theme Customizer. ](https://app.momentscience.com/account/integration/customize#customize)Refer to the [Theme Customizer](docId:6PqgXne5KWHdkuyAwcVW1) 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 :::CodeblockTabs Passing a Callback Function ```javascript 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 :::CodeblockTabs Configuration Structure ```javascript window.AdpxConfig = { accountId: 'YOUR_SDK_ID', autoShow: true, settings: { // Add custom behavior options here }, styles: { // Add style overrides here } }; ``` Example: settings and styles ```javascript window.AdpxConfig = { accountId: 'YOUR_SDK_ID', autoShow: true, settings: { ad_position: 'bottom-right', delay: 2, multi_offer_unit: true, enable_usp: true, show_ads_on_exit: false }, styles: { popup: { background: '#ffffff', borderRadius: { top_left: '12', top_right: '12', bottom_left: '12', bottom_right: '12' }, shadow: '#8f8f8f' }, header: { background: '#0b1937', text: 'Your order is complete', textColor: '#fff', lead_in_text: "Here's something we think you'd love!", lead_in_text_color: '#477ba5' } } }; ``` ::: ## 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_position`is **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](docId:9UkjGFQBK0fvD1Qahw51L) | | `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 `
` 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.](docId:9UkjGFQBK0fvD1Qahw51L) | | `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](https://fonts.google.com/) 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](docId\:MCK87it11JXVj9KYC_543) (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](docId\:MCK87it11JXVj9KYC_543) | | `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_usp`is true.

Learn more about [User Selected Perks (USP)](docId\:MCK87it11JXVj9KYC_543) | | `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](docId\:MCK87it11JXVj9KYC_543) | | `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 [PerksWallet](docId\:EXwIOcsTqW3y6T1XQEHfW) 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](docId\:EXwIOcsTqW3y6T1XQEHfW). | | `perkswallet_show_cta` | Boolean | Controls the visibility of the “Save for later” CTA. If true, the CTA will be shown when `enable_perkswallet`is enabled.

Learn more about [PerksWallet](docId\:EXwIOcsTqW3y6T1XQEHfW). | | `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](docId\:EXwIOcsTqW3y6T1XQEHfW). | ## Overriding Offer Unit Styles You can customize the appearance of the Moments Offer Unit by passing a `styles`object 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. | :::CodeblockTabs Override Offer Style (styles.popup) ```javascript 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". | :::CodeblockTabs Override Header Style ```javascript 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. | ```javascript 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. | :::CodeblockTabs Override Footer Style ```javascript 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). :::hint{type="info"} 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 | :::CodeblockTabs Perkswall and MOU Style ```javascript 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](docId:-LFsS4N-fV4dXSKXSJ24o) ### 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](docId:7_jtaiiskgwAu7cc5Nbp3) ### 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](mailto\:help@Momentscience.com)