Using JS Widget in App Mediation
Implementation process
All the In-App implementation requires consultation with your Account Manager and QA process before going live.
Code Snippet
Regular HTML
<div class="OUTBRAIN"
data-ob-bundleUrl="DROP_STORE_URL_HERE"
data-ob-language="DROP_LANGUAGE_CODE_HERE"
data-widget-id="DROP_WIDGET_ID_HERE"
data-ob-user-id="DROP_ADVERTISING_ID_HERE"
data-ob-installation-key="DROP_PARTNER_KEY_HERE"></div>
<script type="text/javascript" async="async"
src="https://widgets.outbrain.com/outbrain.js"></script>
Google Ad Manager format with macros
Please consult with your Sales Engineer or Partner Manager before using
GAM SafeFrame
The logic to dynamically generate data-ob-bundleUrl and data-ob-language need to be created since GAM does not provide macros.
<div class="OUTBRAIN"
data-ob-bundleUrl="DROP_STORE_URL_HERE"
data-ob-language="DROP_LANGUAGE_CODE_HERE"
data-widget-id="DROP_WIDGET_ID_HERE"
data-ob-user-id="%%ADVERTISING_IDENTIFIER_PLAIN%%"
data-ob-installation-key="DROP_PARTNER_KEY_HERE"
data-consent-string="${GDPR_CONSENT_164}"
data-consent-version="2"
></div>
<script type="text/javascript" async="async"
src="https://widgets.outbrain.com/outbrain.js"></script>
Parameters
| Attribute Name | Requirement | Description | Example value |
|---|---|---|---|
data-ob-bundleUrl | Required for App | The store URL of the App | "https://play.google.com/store/apps/details?id=com.king.candycrushsaga" |
data-ob-language | Required for App and Native Environment | The 2-letter ISO 639-1 language code | "en" |
data-widget-id | Required | The widget id that you received from your Account Manager | "AR_1" |
data-ob-user-id | Required | The Advertising ID(IDFA/AAID) assigned by the device or operating environment | "EA7583CD-A667-48BC-B806-42ECB2B48606" |
data-ob-installation-key | Required | The partner key that you received from your Account Manager | "DEMOP1MN24J3E1MGLQ92067LH" |
data-ob-portalUrl | Only if instructed by SE, Required for Native Environment | A URL representing the context where the ad placement is presented to users. Does not need to be a reachable/crawlable URL. | "http://www.chatPortal.com" |
data-ob-contentUrl | Only if instructed by SE, Required for App WebView with Web content | The permalink of placement to identify the currently displayed content. | "https://www.outbrain.com/blog/123.html" |
data-ob-app-id | Only if instructed by SE, Required for App WebView and Native Environment | The App's unique identifier iOS: Bundle ID, Android: Application ID/Package Name | "com.king.candycrushsaga" |
data-ob-psub | Only if instructed by SE, Optional for Native Environment | String value for additional section-level reporting breakdowns. Allowed characters: alphanumeric and underscore '_'. Requires permission from your Sales Engineer or Partner Manager. | "minus1" |
data-app-ver | Optional | A version number of the App | "1.0.0" |
data-external-id | Optional | A unique key for report breakdowns. See Engage External Id Report API for details | "123abcXYZ" |
data-external-secondary-id | Optional | A secondary key for Engage External Id Report breakdowns as same as external-id. | "456defABC" |
data-consent-string | Optional: Only if TCF API is not available | Base64-encoded consent string, as defined by the IAB for TCF v2.0 | "CO4SiGQO4SiGQAGABBENAzCgAP…(omitted)…YAAAAAAAAAAA" |
data-consent-version | Optional | Version of TCF consent string | "2" |
data-ccpa-string | Optional: Only if US API is not available. | Four digit US privacy string, as defined by IAB for CCPA compatibility. See about IAB CCPA Compliance Framework here | "1YNN" |
data-click-url | Optional | An image pixel URL for tracking clicks on paid recommendations | "https://yourdomain.com/click?123" |
data-dark-mode | Optional | A boolean flag for activating dark mode settings on the widget. Set to true if instructed by Outbrain to show widget in dark mode design. Dark Mode setting need to be set by Outbrain on the widget first. This is not a dynamic state – widget needs reloaded to take effect. | "true" |
data-ob-test | Optional | A boolean flag for testing. Set to true to avoid registering clicks and impressions with Outbrain during development and troubleshooting. This attribute must be removed before releasing to production. | "true" |
Parameters in detail
Bundle URL
The store URL of the App in App distribution platform. Currently Google play store, Apple App store, Facebook App, Huawei App Gallery formats are supported.
| Store Name | URL format | Example Value |
|---|---|---|
| Google Play Store | https://play.google.com/store/apps/details?id=bundleID | "https://play.google.com/store/apps/details?id=com.outbrain" |
| Apple App Store | http://apps.apple.com/country/app/app–name/idapp-ID | "https://apps.apple.com/mt/app/candy-crush-saga/id553834731" |
| Microsoft App Store | https://www.microsoft.com/store/apps/appStoreID | "https://www.microsoft.com/store/apps/9wzdncrfhwd2" |
| Facebook App | https://www.facebook.com/uniqueAppName | "https://www.facebook.com/247solitaire/" |
| Huawei App Gallery | https://appgallery.cloud.huawei.com/ag/n/app/app-ID | "https://appgallery.cloud.huawei.com/ag/n/app/C100995735" |
Advertising ID
It is mandatory to pass the Advertising ID for Outbrain installations in mobile apps, according to Google and Apple guidelines and developer agreements. In compliance with Google and Apple guidelines, if the user is opted out of ad tracking, please pass the value null (case sensitive) as a value
Consent / US Privacy String
Our JS Widget is fully compliant to TCF v2.0 and CCPA. It will automatically fetch consent/US privacy string from CMPs, so there's no need to pass consent string manually. However, if the WebView does not support TCF API or US API, it's possible to pass consent/US privacy string directly to widgets by using the data-consent-string or data-ccpa-string attribute.
Navigate to Paid Recommendations
Use SFSafariViewController(iOS)/ChromeCustomTab(Android) or Safari/Chrome browsers for all paid recommendations. Please make sure to open the Outbrain redirect URL (paid.outbrain.com) directly without any URL manipulation.
Smartfeed Support
Smartfeed is not supported in-App WebView JS Widget installation.
Widget Callback Events
Custom callback scripts can be supported by Widget External Event Handler. For example, the Ad fill status of the widget can be checked by scanning the value of recsNumber at widgetDataReturned event. Widgets must be shown to users even the Ad slots are not fully filled.
Mandatory setup for Android App: Charles Proxy Support
In order to verify that your app is working according to our guidelines, we use a software called Charles Proxy to monitor the networking coming in and out of the app.
For Android 7.0 or newer, you need to add configuration to your app in order to have it trust the SSL certificates generated by Charles SSL Proxying. In order to configure your app to trust Charles, you need to add a Network Security Configuration File to your app.
This file can override the system default, enabling your app to trust user installed CA certificates (e.g. the Charles Root Certificate). You can specify that this only applies in debug builds of your application, so that production builds use the default trust profile.
Add a file res/xml/network_security_config.xml to your app:
<network-security-config>
<debug-overrides>
<trust-anchors>
<!-- Trust user added CAs while debuggable only -->
<certificates src="user" />
</trust-anchors>
</debug-overrides>
</network-security-config>
Then add a reference to this file in your app's manifest, as follows:
<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
<application android:networkSecurityConfig="@xml/network_security_config" ... >
...
</application>
</manifest>