How to Enable Singular Banners (Developers Guide)

Follow
Avatar
Dora Kishinevsky
Updated

Singular Banners is an enterprise feature. To learn more about this feature, reach out to your Customer Success Manager.

Update (March 2023): A new step has been added to allow Singular to receive client hints (learn more).

Singular Banners can be displayed in your mobile website to lead web users seamlessly to your app and display the most relevant app content. Once you enable Singular Banners in your website, your organization can easily design, deploy, and maintain banners through the Singular Banners UI.

Guide For Developers
Prerequisites The Singular Mobile SDK is integrated in your app, including deep link support.
Related Articles
  • How to Create a Singular Banner (Visual Guide)
  • Singular Banners FAQ

Step-by-Step

1

Add the Singular Website SDK Script to Your Site

Singular hosts the SDK JavaScript code on Singular's CDN. Add the following code inside the <head> tag of each page you want to track. This is the code to add to use the version of the SDK that supports banners.

<head>
<!-- Using the latest SDK version   -->
<script
 src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
</script>
</head>
2

Give Singular Permission to Access Client Hints Data

With the new limitations on user agent data in Chromium-based web browsers, rolled out in February-March 2023, advertisers now need to fetch client hints data instead as well as give the Singular Web SDK permission to receive this data. For more information, see the Banners FAQ.

The website needs to:

  1. Start asking for Client Hints (accept-ch header).
  2. Grant Singular permission (as a third party) so that the browser will send us the client hints on the fetch banner requests (permissions-policy header).

Add the following response headers to the page load response:

accept-ch:
sec-ch-ua-model,
sec-ch-ua-platform-version,
sec-ch-ua-full-version-list

permissions-policy:
ch-ua-model=("https://sdk-api-v1.singular.net"),
ch-ua-platform-version=("https://sdk-api-v1.singular.net"),
ch-ua-full-version-list=("https://sdk-api-v1.singular.net")

 
3

Initialize the Singular Website SDK and Display Banner

The SDK initialization code should be called every time a page is loaded. It is a prerequisite to all Singular Banners and/or web attribution functionality.

To initialize the SDK, use the following code. 

  • You will need your SDK Key and SDK Secret, which can be retrieved through the Singular platform at Developer Tools > SDK Keys.
  • You will also need to enter a Product ID for your website. We recommend using reverse DNS notation, e.g., “com.example.site”. This will be used to identify your website throughout the Singular platform.
// Create Singular Banners config object & enable web-to-app support.
// Web-to-app is required if you want to track which ad network
// led the user to your site.
var bannersOptions = new BannersOptions().withWebToAppSupport();

// Create a general SDK config object and enable Singular Banners.
var config = new SingularConfig(sdkKey, sdkSecret,
   productId).withBannersSupport(bannersOptions);

// Initialize the SDK
singularSdk.init(config);

// Display banner
singularSdk.showBanner();

Notes:
4

Reshow Banner on Page Route (Single-Page Applications Only) 

If your application is single-page, you have to hide and re-show the banner on each page route. This ensures that Singular delivers the appropriate banner for your web experience. 

To hide and re-show the banner, use the following code:

singularSdk.hideBanner();
singularSdk.showBanner();

This was the last step of the process for a standard integration. The UA team can now start creating banners by logging into Singular and going to Automation > Banners. The banners will be displayed in your website based on the options selected in Automation > Banners.

The next steps are optional.
5

[Advanced Option] Customize Link Settings

Singular provides a way to personalize the links in the banner through code. 

To personalize links:

  1. Create a LinkParams object and use one or more of the functions below. Do this before calling singularSdk.showBanner().
  2. Then pass the LinkParams object when you call showBanner().

Example:

// Define a LinkParams object
let bannerParams = new LinkParams();

// Configure link options (see details on each option below)
bannerParams.withAndroidRedirect("androidRedirectValue");
bannerParams.withAndroidDL("androidDLParamValue");
bannerParams.withAndroidDDL("androidDDLparamValue");
bannerParams.withIosRedirect("iosRedirectValue");
bannerParams.withIosDL("iosDLValue");
bannerParams.withIosDDL("iosDDLValue");

// Show the banner with the defined options
singularSdk.showBanner(bannerParams);

List of options:

Method Description
withAndroidRedirect Pass a redirect link to your Android app download page, usually a Play Store page.
withAndroidDL Pass a deep link for a page within your Android app.
withAndroidDDL Pass a deferred deep link, i.e., a link to a page in your Android app that the user hasn't installed yet.
withIosRedirect Pass a redirect link to your iOS app download page, usually an App Store page.
withIosDL Pass a deep link to a page within your iOS app.
withIosDDL Pass a deferred deep link, i.e., a link to a page in your iOS app that the user hasn't installed yet.
6

[Advanced Option] Use Code to Force Hiding/Showing of Banners

As mentioned in step 3, if you have a single-page application, you have to use the hideBanner() and showBanner() methods on each page route to ensure the appropriate banner is delivered  (see step 3 above).

hideBanner() and showBanner() are also available to you to use throughout your code if you want to hide a banner that would otherwise be displayed, or re-show a banner that you hid.

Method Description
singularSdk.hideBanner() Hide a visible banner from your page.
singularSdk.showBanner() Show the pre-configured banner.
singularSdk.showBanner(params) Show the pre-configured banner but override links with the options defined in the linkParams object (see step 4).