Web Ads SDK (JS)

Web Ads SDK (hereinafter SDK) is intended for monetization of advertising inventory in web applications ( websites ). The SDK includes:

Advertising SDK - to query and display ads in the app

Before you start

You should have the following paramters to initialize the SDK. If you don't - please ask the technical team to provide it.

bannerURL - API URL of advertising system. For example: https://test.com/
SDK URL - URL for importing SDK into the web application (website). For example: https://test-sdk.com/web-sdk.js

Ads SDK version: 0.5.1

Initialization

The initialization of the library is performed by the developer by calling the method webSDK.init().

typescript

type InitParams = {
  baseUrl: string; // DEPRECATED
  bannerURL: string;
  productURL: string;
  uid?: string;
  sessionId: string;
  debug?: 'error' | 'warn' | 'info' | 'debug';
};

type Init = (params: InitParams) => void;

bannerURL - issued to you URL to request banner creatives from API of advertising system (see above). For example: https://test.com/.
productURL - issued to you URL to request product creatives from API of advertising system (see above). For example: https://test.com/.
sessionId - Unique session id determining the current application session. For example: bfd0620a5017d1362431aea6c1d6e504.
uid - (optional) user unique id. The identifier can be an email hash or a user-specified phone number when registering. For example: bfd0620a5017d1362431aea6c1d6e504.
debug - (optional) flag enables certain level of logging debug information in SDK. Default value is warn .

Place a method call init as early as possible when loading a web page. Better if you do it inside the tag <head>. To do this, open the code of your site and find in it the tag code <head>.

html

<!-- Example -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Web Ads SDK (JS)</title>
    <!-- INSERT SDK CODE FOR INITIALISATION HERE -->
  </head>
</html>

Place the initialization code at the bottom of the heading section above the closing tag </head>:

html

<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.init({
    bannerURL: 'https://test.com/',
    productURL: 'https://test.com/',
    uid: 'bfd0620a5017d1362431aea6c1d6e504',
    sessionId: 'bfd0620a5017d1362431aea6c1d6e504',
  });
</script>

User ID (UID)

Your mobile app can be the following type:

Anonymous - is a public application that does not require user authorization to access the functionality.
AuthN/AuthZ - the user must have an account and be authorized to access the functionality.
Mixed - part of the application functionality is available to the user without authorization, when like another part only after passing one.

The SDK provides a setUserId function, which allows you to set the user ID of the authenticated user. Use this function to set the value of uid for each successful user authentication attempt in your application.

INFO

This function is similar to the field uid in the init function. If the application does not already have user information at the time of the init function call, then this information can be passed later on via the setUserId function.

code exampletypes

html

<div id="placement_id" class="placement"></div>
<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  // Call without uid field
  webSDK.init({
    bannerURL: 'https://test.com/',
    sessionId: 'bfd0620a5017d1362431aea6c1d6e504',
  });
  // Later on SignIn action call the setUserId function
  webSDK.setUserId('testUID');
</script>

export type SetUserId = (uid: string) => void;

uid - (required) Unique user ID, authorized in your mobile app.

Banner is initialized by calling function webSDK.loadBanner().

typescript

type AdSize = {
  w: number;
  h: number;
};

type BannerPlacement = {
  placementId: string;
  origin?: string;
  sizes: AdSize[];
  refresh?: number;
  customParams?: Record<string, unknown>;
};

export type BannerLoad = (placements: BannerPlacement[]) => Promise<void>;

placementId - Advertising placement identifier. For example: "456".
origin - (optional) string that indicates the origin (scheme, hostname, and port) that caused the request.
sizes - list of valid sizes for a banner.
refresh - (optional) parameter that describes the time in seconds after which the new advertisement banner will be loadeded in the same placement automatically. If it is not specified, then the download of advertising creative will happen once.
customParams - (optional) user settings that can be agreed to be sent to the server for further processing.

Place in any, design-appropriate page location div element with the attribute id, which will point to the placement ID. Next to it, place a tag script, with the call of method webSDK.loadBanner().

Attention

Note that the internal content of the div tag is used by the SDK itself to display the banner. Do not place anything in it yourself. Otherwise, an unexpected result may occur during the SDK operation.

html

<div id="placement_id" class="placement"></div>
<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.loadBanner([
    {
      placementId: 'placement_id',
      origin: 'https://domain.com',
      sizes: [{ w: 240, h: 300 }],
      refresh: 30,
      customParams: {
        gdprConsent: 'CPsmEWIPsmEWIABAMBFRACBsABEAAAAgEIYgACJAAYiAAA.QRXwAgAAgivA',
        ccpa: '1YNN',
        coppa: 1,
      },
    },
  ]);
</script>

NoAd

When the loadBanner() function is called and the server responds with status 204 (indicating no BannerCreative object was received), the NoAd logic will handle it.

The NoAdContent event will be generated.
The div element for the advertising banner will not be shown.
If a response with status 204 is received from the first request, a second request for an advertising banner will be made after 3 seconds by default.
If a response with status 204 is received after a series of requests, the refresh parameter will be set to the value from the last 200 response from the server.
Requests will be repeated with the specified settings until a response with status 200 is received. The refresh parameter will be updated from this response.
If refresh was set to zero, then there will be no more repeated requests for the advertising banner.

Product display

Product Banner is a special type of advertising creative for RetailMedia platforms, which uses the SKU product identifier in the RetailMedia platform. In this case, SDK does not render advertising content or perform tracking and landing page navigation functions. In the case of this advertising creative, it is the responsibility zone of the host developer. Having received a response from SDK with a list of creatives and their SKU, the developer forms a display of advertising content based on existing pictures of products in the platform on these SKUs, according to the internal templates and styles, providing a call for the necessary tracking of events.

Product is initialized by calling function webSDK.loadProduct().

typescript

type ProductPlacement = {
  placementId: string;
  origin?: string;
  refresh?: number;
  customParams?: Record<string, unknown>;
};

export type ProductResponse = {
  bids: ProductCreative[];
};

export type ProductLoad = (placements: ProductPlacement[]) => Promise<void>;

Parameters

placementId - Advertising placement identifier. For example: "456".
origin - (optional) string that indicates the origin (scheme, hostname, and port) that caused the request.
refresh - (optional) parameter that describes the time in seconds after which the new advertisement banner will be loadeded in the same placement automatically. If it is not specified, then the download of advertising creative will happen once.
customParams - (optional) user settings that can be agreed to be sent to the server for further processing.

Return value

ProductResponse object with filed bids consisting array of ProductCreative.

Examples

html

<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.loadProduct([
    {
      placementId: 'placement_id',
      origin: 'https://domain.com',
      refresh: 30,
      customParams: {
        gdprConsent: 'CPsmEWIPsmEWIABAMBFRACBsABEAAAAgEIYgACJAAYiAAA.QRXwAgAAgivA',
        ccpa: '1YNN',
        coppa: 1,
      },
    },
  ]);
  webSDK.onEvent(webSDK.Events.LoadDataSuccess, 'placement_id', ({ detail }) =>
    console.log(`'SDK successfully loaded data. Product creative: ${JSON.stringify(detail)} `),
  );
</script>

NoAd

When the loadProduct() function is called and the server responds with status 204 (indicating no BannerCreative object was received), the NoAd logic will handle it because no ad content was found.

The NoAdContent event will be generated for such placements.

Event processing

Event processing of advertising banner display takes place with the help of functions webSDK.onEvent() and webSDK.onEvent(). The events are listed below.

Function webSDK.onEvent() allows you to add functions-handlers (callback) to a specific event display of an advertising banner. Function webSDK.offEvent() removes all handler functions from a specific event display of an advertising banner.

typescript

type onEvent = (event: Events, placementId: string, callback: () => void) => void;

type offEvent = (event: Events, placementId: string) => void;

Events:

LoadDataSuccess - the request to the advertising server successfully returned creative data;
LoadDataFail - the error has occurred while requesting creative data from the advertising server;
LoadContentSuccess - the creative successfully rendered;
LoadContentFail - the error has occurred while rendering creative, creative content has wrong data;
NoAdContent - the request was finished successfully but ad server doesn't have content for this request's params;
Impression - the сreative was shown to the user;
Click - the user clicks on the creative;
Viewable - the creative is in the user’s visual field.

html

<div id="placement_id" class="placement">Placeholder for ad placement</div>
<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.onEvent(webSDK.Events.LoadDataSuccess, 'placement_id', () => console.log('SDK successfully loaded data'));
  webSDK.onEvent(webSDK.Events.LoadContentSuccess, 'placement_id', () =>
    console.log('SDK successfully rendered creative data'),
  );

  webSDK.onEvent(webSDK.Events.LoadDataFail, 'placement_id', () =>
    console.log('The error has occurred while requesting creative data'),
  );
  webSDK.onEvent(webSDK.Events.LoadContentFail, 'placement_id', () =>
    console.log('The error has occurred while rendering creative data'),
  );

  webSDK.onEvent(webSDK.Events.Impression, 'placement_id', () => console.log('The Creative was shown to the user'));
  webSDK.onEvent(webSDK.Events.Click, 'placement_id', () => console.log('The user clicks on the creative'));
  webSDK.onEvent(webSDK.Events.Viewable, 'placement_id', () =>
    console.log('The creative is in the user’s visual field.'),
  );
</script>

Helper types

AdSize

The object type describes the size of the placement. Contains fields corresponding to the width and height of the placement in pixels.

w - width in pixels. For example: 300
h - height in pixels. For example: 250

typescript

type AdSize = {
  w: number;
  h: number;
};

ProductCreative

The object type describes the product creative.

typescript

export type ProductCreative = {
  id: string;
  placementId: string;
  sku: string;
  externalId: string;
  disclaimer?: string;
  tracking?: ProductTracking;
};

id - id of ad request.
placementId - ID of the ad slot. For example: 123456.
sku - unique product identifier.
externalId - external unique ad identifier
disclaimer - (optional) written disclaimer or disclaimer of liability when publishing advertising content.
tracking - (optional) object containing URLs for event tracking ProductTracking

ProductTracking

Object represents tracking urls.

typescript

export type ProductTracking = {
  view: string[];
  click: string[];
  impression: string[];
};

click - list of urls to track click on ads.
impression - list of urls to track impression of ads.
view - list of urls to track viewability of ads.

Web Ads SDK (JS) ​

Initialization ​

User ID (UID) ​

Banner display ​

NoAd ​

Product display ​

Parameters ​

Return value ​

Examples ​

NoAd ​

Event processing ​

Helper types ​

AdSize ​

ProductCreative ​

ProductTracking ​

Web Ads SDK (JS)

Initialization

User ID (UID)

Banner display

NoAd

Product display

Parameters

Return value

Examples

NoAd

Event processing

Helper types

AdSize

ProductCreative

ProductTracking