JS SDK (for Websites)

Introduction
Adding an AdsPostX placement to your online store, website, mobile app or other user experience is designed to be a relatively straight-forward process and can typically be implemented within hours.
Your account manager will provide you with your SDK ID (also referred to as an "accountId") or you may obtain it by logging into the AdsPostX dashboard with instructions  here﻿.
Quickstart
The playable demo below is oriented towards integrating AdsPostX with a website using the JS.  If you are interested in integrating AdsPostX with a mobile app, head to our Mobile SDK docs﻿.
<div style="position: relative; padding-bottom: calc(48.552083333333336% + 44px); height: 0;"><iframe src="https://app.supademo.com/embed/dwr_ejrlgKVuDj08O4DSS" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
<div style="position: relative; padding-bottom: calc(48.552083333333336% + 44px); height: 0;"><iframe src="https://app.supademo.com/embed/dwr_ejrlgKVuDj08O4DSS" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
﻿
Simply cut and paste the integration code that you obtain from the AdsPostX dashboard or as supplied before the </head> tag on your website.  It should look like the following:
JS
<script>
    (function (window) {
        window.AdpxConfig = {
            accountId: 'YOUR_ACCOUNT_ID_HERE'
		};

		/**
		 * Fill this object with user-specific values from your website.These
		 * values are picked up by the SDK.
		 */
	    window.AdpxUser = {
		    email: '',
			firstname: '',
			lastname: '',
			mobile: '',
			confirmationref: '',
			amount: '',
			currency: '',
			paymenttype: '',
			ccbin: '',
			zipcode: '',
			country: '',
			language: '',
			tags: '',
			subid: null
		}
    })(window.self !== window.top ? window.top : window);
</script>

<script type="module">
    (async function (window) {
        const target = window.document.head || window.document.body;
        const script = window.document.createElement('script');
        script.type = 'text/javascript';
        script.src = 'https://cdn.pubtailer.com/launcher.min.js';
        script.importance = 'high';
        script.crossOrigin = 'anonymous';
        script.async = true;
        script.id = 'adpx-launcher';
        target.appendChild(script);
        await new Promise(function (resolve) {
        	window.Adpx
            	? resolve()
            	: window.document
                	.getElementById('adpx-launcher')
                	.addEventListener('load', function () { resolve(); })
        });
        window.Adpx.init({
            accountId: window.AdpxConfig.accountId,
			// set this to `false` to trigger Offers overlay
			// programatically with `window.Adpx.show()`
			autoShow: true,
		});
    })(window.self !== window.top ? window.top : window);
</script>
<script>
    (function (window) {
        window.AdpxConfig = {
            accountId: 'YOUR_ACCOUNT_ID_HERE'
		};

		/**
		 * Fill this object with user-specific values from your website.These
		 * values are picked up by the SDK.
		 */
	    window.AdpxUser = {
		    email: '',
			firstname: '',
			lastname: '',
			mobile: '',
			confirmationref: '',
			amount: '',
			currency: '',
			paymenttype: '',
			ccbin: '',
			zipcode: '',
			country: '',
			language: '',
			tags: '',
			subid: null
		}
    })(window.self !== window.top ? window.top : window);
</script>

<script type="module">
    (async function (window) {
        const target = window.document.head || window.document.body;
        const script = window.document.createElement('script');
        script.type = 'text/javascript';
        script.src = 'https://cdn.pubtailer.com/launcher.min.js';
        script.importance = 'high';
        script.crossOrigin = 'anonymous';
        script.async = true;
        script.id = 'adpx-launcher';
        target.appendChild(script);
        await new Promise(function (resolve) {
        	window.Adpx
            	? resolve()
            	: window.document
                	.getElementById('adpx-launcher')
                	.addEventListener('load', function () { resolve(); })
        });
        window.Adpx.init({
            accountId: window.AdpxConfig.accountId,
			// set this to `false` to trigger Offers overlay
			// programatically with `window.Adpx.show()`
			autoShow: true,
		});
    })(window.self !== window.top ? window.top : window);
</script>
﻿
Before continuing with implementation, take a look at your integration code as inserted to ensure that the accountId matches your accountId.
Initialization Options
The following attributes are supported by the init function.
accountId - string  Your SDK ID from Dashboard; mandatory
autoLoad - boolean Default: true - The ADPX SDK fetches available Offers as soon as the SDK is ready. When set to false, the ADPX SDK's refresh function must be explicitly called to fetch and display Offers. 
autoShow - boolean  Default: true- When false ADPX SDK's show  function must be called to trigger Offers overlay. If autoLoad is set to false, autoShow does not have any effect.
settings - object optionally override some Dashboard settings. See section Overriding Settings & Styles below.
styles - object apply custom styling at runtime. See section Overriding Settings & Styles  below.
Passing in payload values (customer and/or order information)
To be able to identify a customer, please populate the global window.AdpxUser object's properties in the supplied code with information related to the customer. This is the payload that sent to AdsPostX. We recommend supplying the email, firstname, confirmationref, mobile, and zipcode parameters at the minimum.
JS
    window.AdpxUser = {
        email: "REPLACE_WITH_CUSTOMER_EMAIL",
        firstname: "REPLACE_WITH_FIRST_NAME",
        lastname: "",
        mobile: "REPLACE_WITH_CUSTOMER_MOBILE_NUMBER",
        confirmationref: "REPLACE_WITH_ORDER_NUMBER",
        amount: "",
        currency: "",
        paymenttype: "",
        ccbin: "",
        zipcode: "REPLACE_WITH_CUSTOMER_ZIP",
        country: "",
        language: "",
        tags: "",
        subid: ""
    };
    window.AdpxUser = {
        email: "REPLACE_WITH_CUSTOMER_EMAIL",
        firstname: "REPLACE_WITH_FIRST_NAME",
        lastname: "",
        mobile: "REPLACE_WITH_CUSTOMER_MOBILE_NUMBER",
        confirmationref: "REPLACE_WITH_ORDER_NUMBER",
        amount: "",
        currency: "",
        paymenttype: "",
        ccbin: "",
        zipcode: "REPLACE_WITH_CUSTOMER_ZIP",
        country: "",
        language: "",
        tags: "",
        subid: ""
    };
﻿
You may populate these values using a server-side routine or add them client-side any time prior to initializing the SDK with the window.Adpx.init() call.
To add or update payload data after initialization, see the section Delaying Offers﻿ below.
Identifying the origin source of your AdsPostX unit(s)
To better understand performance of your AdsPostX unit(s) and/or to segment traffic, you may pass a subid parameter in the customer object. 
JS
    window.AdpxUser = {
        // Payload attributes here.
        
        subid: "REPLACE_WITH_SUBID_VALUE"
    };
    window.AdpxUser = {
        // Payload attributes here.
        
        subid: "REPLACE_WITH_SUBID_VALUE"
    };
﻿
Replace the REPLACE_WITH_SUBID_VALUE text with any text that you would like to identify impressions, clicks and conversions with.
Passing Contextual Information
The tags attribute can be used to provide additional contextual information that would help the SDK deliver more relevant and personalised Offers.
The tags attribute can be a comma-separated list of values or a JS array of strings:
JS
window.AdpxUser = {
  // Payload attributes here.

  tags: "top-category, sub-category",
  // OR
  tags: [ 'category-one', 'category-two' ],
};
window.AdpxUser = {
  // Payload attributes here.

  tags: "top-category, sub-category",
  // OR
  tags: [ 'category-one', 'category-two' ],
};
﻿
Custom Key-Value payload attributes
You many also add any custom key-value payload attributes to the payload that you want to use to add additional details. 
All payload attributes are passed back on conversion reports and can be reported on in relation to impressions and clicks. 
As shown below as an example we can pass in membershipID and source as custom key-value payload attributes: 
JS
window.AdpxUser = {
  // Payload attributes here.

  membershipID: "A45GRE987343PKD",
  source: "email",
};
window.AdpxUser = {
  // Payload attributes here.

  membershipID: "A45GRE987343PKD",
  source: "email",
};
﻿
Verify that your integration code is working
To ensure that your integration code has correctly been implemented, visit the page containing the integration code to confirm that Offers are displaying.  Additionally, if you are passing payload values, verify that the preferred parameters are in fact provided in the window.AdpxUser object.
Styling AdsPostX for your website
AdsPostX provides an easy way to stylize the AdsPostX unit that appears on your website.  Simply, log into the AdsPostX dashboard, visit Integrations, select your integration type, and select Configure and follow the steps as indicated.
Callback Function
The AdsPostX SDK accepts a callback function that will be invoked at various points during the lifecycle of the SDK, allowing you to better tailor the user experience.
The callback function should be passed as the second paramter to the init  function. The following example illustrates the basic usage.
JS
window.Adpx.init({
    accountId: 'YOUR_ACCOUNT_ID_HERE',
    dev: false
}, (event, payload) => {
    console.log('Received event with payload from AdsPostX SDK:', event, payload);
});
window.Adpx.init({
    accountId: 'YOUR_ACCOUNT_ID_HERE',
    dev: false
}, (event, payload) => {
    console.log('Received event with payload from AdsPostX SDK:', event, payload);
});
﻿
This callback function can be used to trigger additional user experiences based on events fired by the AdsPostX SDK. 
For example, the following example triggers a survey via a showMySurveys() function after the user closes the AdsPostX unit(s) or after the user has browsed through all Offers presented.
JS
window.Adpx.init({
    accountId: 'YOUR_ACCOUNT_ID_HERE',
    dev: false
}, (event, payload) => {
    console.log('Received event with payload from AdsPostX SDK:', event, payload);

    if (event === 'closed_ads') {
        // user closed the AdsPostX Offers unit; show your surveys
        showMySurveys();
        return;
    }

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

    if (event === 'ad_not_taken') {
        console.log('User passed on offer ' + payload.current + ' of ' + payload.total);
        return;
    }
});
window.Adpx.init({
    accountId: 'YOUR_ACCOUNT_ID_HERE',
    dev: false
}, (event, payload) => {
    console.log('Received event with payload from AdsPostX SDK:', event, payload);

    if (event === 'closed_ads') {
        // user closed the AdsPostX Offers unit; show your surveys
        showMySurveys();
        return;
    }

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

    if (event === 'ad_not_taken') {
        console.log('User passed on offer ' + payload.current + ' of ' + payload.total);
        return;
    }
});
﻿
The following is a list of events received by the callback function with details of the payload  object, if any:
ads_found - denotes that the SDK found Offers for the user. The following attributes are present in payload  received by the callback:
total integer; the total number of Offers returned by the SDK
no_ads_found - no relevant Offers were returned by the SDK. No further events will be triggered after this event.
ad_taken - the user has clicked an Offer (which opens in a new tab). The following attributes are present in the payload  received by the callback:
target_url url; link to the Offer
total integer; the total number of Offers returned by the SDK
current integer; position of current Offer in the list of Offers presented
ad_not_taken - the user did not click the current Offer but browsed to the next one. The following attributes are present in the payload received by the callback:
total  integer; the total number of Offers returned by the SDK
current integer; position of current Offer in the list of Offers presented
closed_ads - the user closed the Offers unit. This event is also fired after user browses through all the Offers presented.
Overriding Settings & Styles
ADPX SDK provides the ability to override the settings and styles at runtime, by passing the optional settings and styles attributes in the initialization options.
The following properties are supported in the settings override:
ad_position string Set the position of the Offers Unit on the screen. Valid values:
center
top-center
top-right
right-center
bottom-right
bottom-center
bottom-left
right-center
top-left
darken_bg boolean when true, the Offers Unit appears as an overlay and disables user interaction with the background page. This setting applies only when ad_position is set to center
darken_bg_non_centered boolean same as darken_bg but applied when ad_position is set to any value other than center
delay integer Delay, in seconds, between successfully fetching the Offers and displaying the Offers unit on screen.
privacy_policyurl Link, if any, to your Privacy Policy
screen_margin integer margin between the Offers unit and the closest edges of the screen.
show_disclaimer boolean show the disclaimer text in the footer of the Offers unit
﻿
The styles override should have the following structure:
JS
{
  // Customizing the Offers Unit.
  "popup": {
    "background": "#ffffff",
    "borderRadius": {
      "bottom_left": "12",
      "bottom_right": "12",
      "top_left": "12",
      "top_right": "12"
    },
    "lightBox": "#000",
    "shadow": "#8f8f8f"
  }
  
  // Customize the header of the Offers Unit
  "header": {
    "background": "#0b1937",
    "fontSize": 16,
    "lead_in_text": "Here's something we think you'd like!",
    "lead_in_text_color": "#477ba5",
    "text": "{{firstname}}, Your order ({{confirmationref}}) is complete!",
    "textColor": "#fff"
  },
  
  // Customize the Offers Unit content
  "offerText": {
    // styles for the Negative CTA
    "buttonNo": {
      "background": "#fff",
      "color": "#6B7280",
      "hover": "#E5E7EB",
      "stroke": "#9CA3AF"
    },
    // Styles for the Positive CTA
    "buttonYes": {
      "background": "#000000",
      "color": "#fff",
      "hover": "#0b1937",
      "stroke": "#0b1937"
    },
    // font and colors of the Offers unit body
    "font": "Roboto",
    "fontSize": 14,
    "textColor": "#000"
  },

  // Override the styles and content of the footer
  "footer": {
    "disclaimer": "",
    "publisher_name": "AdsPostX",
    "publisher_privacy_policy": null,
    "text": "Powered by AdsPostX"
  }
}
{
  // Customizing the Offers Unit.
  "popup": {
    "background": "#ffffff",
    "borderRadius": {
      "bottom_left": "12",
      "bottom_right": "12",
      "top_left": "12",
      "top_right": "12"
    },
    "lightBox": "#000",
    "shadow": "#8f8f8f"
  }
  
  // Customize the header of the Offers Unit
  "header": {
    "background": "#0b1937",
    "fontSize": 16,
    "lead_in_text": "Here's something we think you'd like!",
    "lead_in_text_color": "#477ba5",
    "text": "{{firstname}}, Your order ({{confirmationref}}) is complete!",
    "textColor": "#fff"
  },
  
  // Customize the Offers Unit content
  "offerText": {
    // styles for the Negative CTA
    "buttonNo": {
      "background": "#fff",
      "color": "#6B7280",
      "hover": "#E5E7EB",
      "stroke": "#9CA3AF"
    },
    // Styles for the Positive CTA
    "buttonYes": {
      "background": "#000000",
      "color": "#fff",
      "hover": "#0b1937",
      "stroke": "#0b1937"
    },
    // font and colors of the Offers unit body
    "font": "Roboto",
    "fontSize": 14,
    "textColor": "#000"
  },

  // Override the styles and content of the footer
  "footer": {
    "disclaimer": "",
    "publisher_name": "AdsPostX",
    "publisher_privacy_policy": null,
    "text": "Powered by AdsPostX"
  }
}
﻿
Controlling when to display the AdsPostX Unit
The default behavior of the AdsPostX Web SDK is to: 
Fetch Offers as soon as the SDK is ready (configuration parameter boolean autoLoad) 
Display the Offers as soon as they are successfully fetched (configuration parameter boolean autoShow)
To control the first step, see Delaying the AdsPostX Unit﻿ below.
The initialization attribute autoShow controls the second step of this behavior. By default the autoShow attribute is true . 
autoShow can be set to false and the Offers overlay will be suppressed when the SDK is ready. To display the Offers overlay, use the show function.
JS
window.Adpx.init({
  accountId: 'YOUR_ACCOUNT_ID_HERE',
  // autoShow is set to false - Offers have already 
  // been fetched wait for a call to  `window.Adpx.show()`
  // to show the Offers
  autoShow: false
});

/**
 * Display the Offers unit the first time.
 */
window.Adpx.show();

/**
 * Display the Offers unit after it has been closed once.
 */
window.Adpx.reload();

window.Adpx.init({
  accountId: 'YOUR_ACCOUNT_ID_HERE',
  // autoShow is set to false - Offers have already 
  // been fetched wait for a call to  `window.Adpx.show()`
  // to show the Offers
  autoShow: false
});

/**
 * Display the Offers unit the first time.
 */
window.Adpx.show();

/**
 * Display the Offers unit after it has been closed once.
 */
window.Adpx.reload();
﻿
By default when the SDK is loaded, Offers are automatically fetched, displayed and an impression is recorded. autoShow controls if they are displayed upon SDK load or not. 
The show function can be called only once during the lifecycle of the SDK. All subsequent calls to show function will fail with an error.
Re-calling AdsPostX
The SDK provides a method that will allow the AdsPostX unit to display again after it has been dismissed.  This is helpful in case the unit is accidentally closed by a customer or the customer may want to re-visit the Offers.  
Simply call the following function: 
JS
window.Adpx.reload();
window.Adpx.reload();
﻿
The reload function does not fetch a new set of Offers. It simply displays any previously fetched set of Offers (starting with the first Offer).
Delaying the AdsPostX Unit
The SDK can also be configured to delay the retrieval and display of offers. This can be particularly useful when integrating on a single-page application (SPA), or when payload attributes have to be collected in multiple steps across the user journey before the Offers can be fetched and displayed.
The autoLoad configuration parameter can be used to delay the fetching of the Offers.

In addition the setPayload  function can optionally be used to update the payload parameters. 

Finally once we're ready to fetch and display Offers, the refresh function should be used.
JS
window.Adpx.init({
  accountId: 'YOUR_ACCOUNT_ID_HERE',
  // autoLoad is set to false - wait for a call to
  // `window.Adpx.refresh()`
  // to fetch and show the Offers
  autoLoad: false
});

// Update the payload as needed
window.Adpx.setPayload({ category: 'new-user' });

// Payload can be updated as many times as needed
window.Adpx.setPayload({ subCategory: 'car-owner' });

/**
 * Display the Offers unit.
 */
window.Adpx.refresh();

window.Adpx.init({
  accountId: 'YOUR_ACCOUNT_ID_HERE',
  // autoLoad is set to false - wait for a call to
  // `window.Adpx.refresh()`
  // to fetch and show the Offers
  autoLoad: false
});

// Update the payload as needed
window.Adpx.setPayload({ category: 'new-user' });

// Payload can be updated as many times as needed
window.Adpx.setPayload({ subCategory: 'car-owner' });

/**
 * Display the Offers unit.
 */
window.Adpx.refresh();
﻿
By default autoLoad is set to true  and when the SDK is loaded, Offers are automatically fetched and an impression is recorded. When autoLoad is set to false the SDK does not fetch any Offers and no impressions are recorded.

The refresh function will fetch a new set of Offers thus an impression will be recorded.
The following list explains the behavior of the SDK for all possible values of autoLoad and autoShow:
autoLoad: true and autoShow: true - this is the default configuration. The Offers are fetched as soon as the SDK is ready, and are displayed as soon as they have been successfully fetched.
autoLoad: false and autoShow: true - the Offers should be explicitly fetched with a call to window.Adpx.refresh(). The Offers are displayed as soon as they have been successfully fetched.
autoLoad: false and autoShow: false - the Offers should be explicitly fetched with a call to window.Adpx.refresh(). The Offers should be displayed with a call to window.Adpx.reload()
autoLoad: true and autoShow: false - the Offers are fetched as soon as the SDK is ready. The Offers should be displayed with a call to window.Adpx.reload()
Need help?
If you're running into any issues while going through the integration process, feel free to contact us at help@adspostx.com.
TABLE OF CONTENTS
Introduction
Quickstart
Initialization Options
Passing in payload values (customer and/or order information)
Identifying the origin source of your AdsPostX unit(s)
Passing Contextual Information
Custom Key-Value payload attributes
Verify that your integration code is working
Styling AdsPostX for your website
Callback Function
Overriding Settings & Styles
Controlling when to display the AdsPostX Unit
Re-calling AdsPostX
Delaying the AdsPostX Unit
Need help?