Smart Banners—mobile web-to-app (for developers)

At a glance: Add the Smart Banners SDK to your website so marketers can convert your website visitors into mobile app users.

Related reading: Smart Banners (for marketers)

Overview

AppsFlyer provides a Smart Banner SDK that advertisers integrate into their websites. The purpose of the SDK is to pull all the required data to dynamically display the Smart Banners. The Smart Banners SDK also automatically builds the proper attribution links, so you don't need to build them manually.

Therefore, the Smart Banner SDK should be accessible from all pages displaying your mobile banners.

The Smart Banner SDK authenticates using the unique Web key, which you can get from the Website workplace.

Code snippet

 Note

Starting January 1st, 2020 the SDK for Smart Banners lets you use both Smart Banners and People-based Attribution on your website. The SDK snippets below contain two examples:

If you already have the standalone PBA Web SDK, remove it and replace it with the Web SDK for both Smart Banners and People-based Attribution; do not simply add the standalone Web SDK for Smart Banners. 

Include this code snippet in the <head> tag of every page displaying your mobile banners.

SDK snippet Old SDK snippet - deprecated

AppsFlyer web SDK for Smart Banners only

  1. Replace the YOUR_WEB_KEY placeholder in the script with your Web key. The web key is created when you create a new Website workplace.
  2. Paste this code snippet in the head tag on your website. Make sure to paste it near the top of the head tag.
<script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyer.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","banners",{banners: {key: "YOUR_WEB_KEY"}});

// Smart Banners are by default set to the max z-index value, so they won't be hidden by the website elements. This can be changed if you want some website components to be on top of the banner.
AF('banners', 'showBanner', { bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"}});
</script>

AppsFlyer web SDK for Smart Banners and people-based attribution

  1. Replace the YOUR_WEB_KEY placeholder in the script with your Web key. The web key is created when you create a new Website workplace.
  2. Replace the YOUR_PBA_KEY placeholder in the script with your web dev key. The web dev key is created when you create a brand bundle. 
  3. Paste this code snippet in the head tag on your website. Make sure to paste it near the top of the head tag.
<script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyer.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF", "pba,banners",{pba: {webAppId: "YOUR_PBA_KEY"}, banners: {key: "YOUR_WEB_KEY"}});

// Smart Banners are by default set to the max z-index value, so they won't be hidden by the website elements. This can be changed if you want some website components to be on top of the banner.
AF('banners', 'showBanner', { bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"}});
</script>

Adding the SDK using tag managers

You can use tag managers to add the Smart Banners SDK to your website.

Google Tag Manager Adobe Launch Tag Manager
  1. In GTM, create a new tag.
  2. Name the tag, click Tag Configuration, and select Custom HTML.

    smart_banners_gtm.png

  3. In the HTML box, paste the SDK snippet. Replace YOUR-BANNER-KEY in the snippet with your actual banner key. Note: See also how to integrate PBA web SDK with Smart Banners

    smart_banners_gtm_sdk_snippet.png

  4. Click Triggering and create a new trigger by clicking on the plus icon at the top right-hand corner of the screen.
  5. Name the trigger, click Trigger Configuration, and choose Page View.
  6. If you want the banner to show up on all pages, select All Page Views. If you want the banner to show up on selected pages, select Some Page Views and define the condition to trigger the tag. To learn more about triggers, read GTM's documentation.

    smart_banners_gtm_trigger.png

  7. Click Save at the top right-hand corner.
  8. Return to the tag configuration screen. Verify that all is set and click Save at the top right-hand corner.
  9. Publish your GTM container. 

SDK functions

showBanner

Purpose: 

Start showing the Smart Banner according to the banner key provided in the snippet.

Note: Don't use this function when implementing Smart Banners in a wrapper/hybrid app to load the banner page from the app (and not from the browser), as using showBanner will display the banner within the app. If you do use showBanner for a wrapper/hybrid app, use hideBanner for mobile app loads.

Parameters (optional):

  • bannerContainerQuery
    If passed, the SDK tries to locate an element in the page with this query and treats it as the entry point for the banner placement. Otherwise, document.body is used.
  • bannerZIndex
    Smart Banners are by default set to the max z-index value, so they won't be hidden by the website elements. This can be changed if you want some website components to be on top of the banner.
  • additionalParams
    If passed, these parameters (for example, deep_link_value) are added as query parameters to the OneLink URL. 

Example:

New SDK Old SDK - deprecated
AF('banners', 'showBanner', { bannerContainerQuery: "#container-id",
              bannerZIndex: 1000,              
              additionalParams: { p1: "v1", p2: "v2"...}});

updateParams

Purpose

Programmatically add up to 10 parameters (for example, deep_link_value) to the OneLink URL assigned to the call-to-action (CTA) button, after the banner displays. 

The input is an object with parameter keys and values.

  • A key can’t have an empty value.
  • A key can’t be named: undefined, null, NaN, or arg
  • Invalid characters:
    • Key: /, \, *, !, @, #, ?, $, %, ^, &, ~, `, =, +, ', ", ;, :, >, <
    • Value = \, ;, $, >, <, ^, #, `

Example

AF ("banners", "updateParams", {p1: "v1", p2: "v2"...})

Considerations

  • The parameters are added as query parameters to the OneLink URL. 
  • When you use updateParams to add parameters, the impression URL is different than the click URL.
  • Parameters added don’t replace those on the original OneLink URL. If the parameter you add is already in the OneLink URL, it doesn’t change. 
  • If updateParams is called more than once, only the parameters from the last call are added to the URL.
  • This method doesn't work with the deprecated Smart Banner web SDK.

hideBanner

Purpose

Programmatically remove any displayed banner from the page (e.g. after displaying for X seconds).

AF('banners', 'hideBanner')

disableBanners - deprecated

Purpose

This function is only available in the old Smart Banners SDK and is going to be deprecated.

Disable the web SDK from displaying banners and communicating with AppsFlyer servers.

disableTracking - deprecated

Purpose

This function is only available in the old Smart Banners SDK and is going to be deprecated.

Disable the web SDK and clear traces of collected info from the browser (i.e. local-storage, cookies, etc.).

setAdditionalParams - deprecated

Purpose

This function is only available in the old Smart Banners SDK and is going to be deprecated.

set additionalParams to the OneLink before calling showBanner. The parameters are appended on the OneLink URL behind the banner.

Parameters

  • Params
    Map of key/value parameters that can override any pre-existing attribution link parameters (besides the pid value).

Usage example

You want to differentiate between landing pages using specific parameters. To do so, you can append additional parameters to the OneLink behind the banner. When a user installs your app after clicking the banner, the parameters on the OneLink appear in the raw data for you to analyze. The code example below makes use of the af_sub1 parameter.

// call this method before calling showBanner()
setAdditionalParameters('af_sub': 'custom_paramter_value')

The format of the final OneLink is this: subdomain.onelink.me/onelink-id?pid=af_banner&c=campaign&af_sub1=custom_paramter_value.

The subdomain and OneLink ID are taken from the OneLink template.

For example: ab12.onelink.me/xyz1?pid=af_banner&c=summer_campaign&af_sub1=uk_landing_page.

You can use any valid parameter. For more information on attribution link parameters, see here. Make sure not to override the pid and c parameters, because these already exist on the attribution link behind the banner.

getAdditionalParams- deprecated

Purpose

This function is only available in the old Smart Banners SDK and is going to be deprecated.

Get the current additionalParams object.

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.