Skip to main content

Getting Started

caution

Please Note The following instructions are mandatory to ensure app compliance. Please make sure to follow the entire guide before submitting your app to Outbrain QA.

Intro​

This document describes the Outbrain mobile SDK for the Android platform. It is intended for Android mobile app developers who want to integrate the Outbrain SDK into their code. The document describes the main Outbrain interface functions.

Compatibility and Requirements​

The Outbrain SDK is a framework, and is compatible with Android API 21 and upward.

Outbrain SDKRequirements
Min SDKAPI 21 \ 5.0
Build SDKAPI 34 \ 14.0
LanguagesJava
DevicesAny Android compatible Devices
SDK SizeOutbrainSDK adds about 100KB to your release app.
IDEAndroid Studio

Outbrain Application Review​

A finalized build must be sent to Outbrain QA at least one week (5 working days) prior to your anticipated release date. We may request changes that will require additional dev resources and could delay your release.

We reserve the right to remove our recommendations or restrict the app from generating Outbrain revenue if required changes are not incorporated prior to release. Builds can be submitted via TestFlight or HockeyApp according to the following table:

Publisher LocationEmail
US & LatAmusqa@outbrain.com
EU, APAC & EMEAilqa@outbrain.com

Your Account Manager can provide more details.​

Mandatory Setup - 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 example this is how we can verify that Viewability is implemented correctly.

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>

Add a reference to this file in your app's manifest:​

<?xml version="1.0" encoding="utf-8"?>
<manifest>
    <application>
           android:networkSecurityConfig="@xml/network_security_config"
           android:theme="@style/MyTheme" ... >
        ...
    </application>
</manifest>

Integrating with the Outbrain SDK​

Please follow the instructions on Download Links to add Outbrain SDK as a dependency to your app.

Initializing the Outbrain SDK​

The Outbrain Class​

The Outbrain class defines a singleton object that is your main interface with the Outbrain SDK. Your app calls its public static methods in order to interact with the Outbrain server. There is no need to create the Outbrain instance it's a singleton object and is created automatically.

Registering Your App’s Configuration​

You will need to register your app's Outbrain configuration once during the initialization of your app, in the Application class onCreate() method. You should call register() before calling any other Outbrain method.

The register() function takes two parameters:​

  • appContext - your ApplicationContext object.
  • appKey - which is a string that contains the partner key you've received from your Outbrain account manager.

Here is an example of how to call Outbrain.register():

try {
    Outbrain.register(appContext, appKey);
}
catch (OutbrainException ex)
{
    // handle exception
}

Working in Test Mode​

While you are developing your app and debugging the integration with Outbrain, you must configure the SDK to work in test mode. This prevents Outbrain from performing operational actions such as reporting and billing, for clicks that were not made by your app's users.

Here is an example:

if (BuildConfig.DEBUG) {
    Outbrain.setTestMode(true); // enable test mode when debugging
}

During the development and testing phase, call setTestMode during your app's initialization, but remember to remove this call before submitting your app to the app store.

Simulate Location (Geo)​

When in testMode it's also possible to simulate location in order for Outbrain servers to return recs according to set location. An example use-case for this would be app developers in India trying to simulate recs for UK audience.

Here is an example for setting US location

if (BuildConfig.DEBUG) {
    Outbrain.testLocation("us");
}

Regular Widget​

Please follow the instructions on this page to learn how you can use regular widgets (non-Smartfeed) in your app.

Smartfeed Bridge Widget​

Please follow the instructions on this page to learn how you can use the Bridge widget in your app.

GDPR Support​

Outbrain SDK supports the IAB guidance and solutions for the requirements of the General Data Protection Regulation.

In February 2017, the IAB Europe assembled parties representing both the supply and demand sides of the digital advertising ecosystem, to work collectively on guidance and solutions to the requirements of the General Data Protection Regulation (GDPR). That working group is known as the GDPR Implementation Working Group (GIG). One of the sub-groups within the GIG was tasked with developing guidance on consent as a legal basis for processing personal data. Out of that effort, an additional working group was formed to develop a technical solution to the challenge of obtaining and disseminating consumer consent to the various parties relying on it as a legal basis of processing personal data.

Proguard Rules​

### OKHTTP
-dontnote okhttp3.internal.Platform

### OKIO
-dontwarn okio.Okio
-dontwarn okio.DeflaterSink

## To safely use ProGuard with Google Mobile Ads, add the following to your ProGuard config:
-keep public class com.google.android.gms.ads.** {
    public *;
}

-keep public class com.google.ads.** {
    public *;
}

-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**

-keep class com.yarolegovich.discretescrollview.** { *; }

-keepattributes Signature
-keepattributes Annotation
-keep class okhttp3.** { *; }
-keep interface okhttp3.** { *; }
-dontwarn okhttp3.**
-dontwarn okio.**

-dontwarn org.apache.commons.text.**