Overview

OBSDK is the generic name of Outbrain’s API wrapper library.
The library allows you to fetch recommendations, originating from a specific document and/or a general source.
It allows you to register a click inside Outbrain’s back-end.
It allows you to display the recommendation document either natively, in a hybrid way or to redirect to the mobile browser.

Sample Apps

The following sample apps are included with the OBSDK zip file. The sample apps are Gradle based and it is recommended to view and run those apps from Android Studio. Both apps compile with Android API 23 (Android M).

Catalog

Outbrain’s catalog app demonstrates our recommended layouts. It is designed and implemented so that importing it into your app is as easy as copy-pasting the layouts codes.

Journal

Outbrain’s Journal is a list of how-to’s. It is implemented in a live publisher mode, using the layouts taken from the Catalog app.

Download

Please download the sample apps from this url: https://developeroprod.wpengine.com/Downloads/Android/OBSDK-Android.zip

Setup

Both samples are ready to use, from Android Studio, import the project you want to use. Keep all the default settings such as name, API level, etc.
Click “Run” and watch the apps in action. Notice both projects support API level >= 13. (Android 3.2)

Android Studio 1.3

• Drag the OBSDK.jar into the libs/ folder of your project
• Right click on the file inside the IDE
• Click ‘Add as Library’.

Technical Documentation

Requirements

OBSDK requires API level >= 8

Permissions

OBSDK requires the INTERNET permission to be added to your app’s manifest file, if not already added.

Initialization

// Import the Outbrain SDK
import com.outbrain.OBSDK.Outbrain;


    public void onCreate(Bundle savedBundle) {
        super.onCreate(savedBundle);
        setContentView(R.layout.my_activity);

        // Initialize the Outbrain SDK with context
        Outbrain.register(getApplicationContext());
        ...
    }

Configuration file

OBSDK requires your app to include the OBConfig.json file under your assets/ folder.
OBConfig.json should include the PartnerKey parameter, with a unique key you have gotten from Outbrain.

• Example Configuration file:

           {
             // Replace '<YourPartnerKey>' with the partner key given to you by Outbrain
             "PartnerKey":"<YourPartnerKey>"  
           }
  

Fetching

This code fetches the Outbrain recommendations into the app.

OBRequest

– url – The URL that identifies the specific content you want recommendations for. – Mandatory

• widgetId – A unique ID that identifies a specific widget within your application. – Mandatory

• widgetIndex – The zero-based index of a given widget on a page.
  (This will usually be 0 unless you have more than one widget on a page) – Mandatory

• isHomepage – A boolean indicating whether this is a “Homepage” request. For more information about “Homepage” requests, please contact Outbrain’s Account Manager. Optional

• source – See Complex Installation – Optional

• mobileId – See Complex Installation – Optional

  { 
      int widgetIndex = 0;
      String widgetId = "AR_1";  //<-- Replace this with your widgetID provided by Outbrain.
      String url = "http://somecontenturl.com/2007/10/somearticle";
      OBRequest request = new OBRequest(url, widgetId, widgetIndex);
      // Now fetch the actual recommendations using this request object.
      // Delegate style
      Outbrain.fetchRecommendations(request, this); //'this' is the listener in the current       implementation
  }
  
  @Override
  public void onOutbrainRecommendationsSuccess(final OBRecommendationsResponse        recommendations) {
      //Do some UI stuff
  }
  
  @Override
  public void onOutbrainRecommendationsFailure(Exception ex) {
      //Handle error
  }
  

RecommendationsListener

When fetching for recommendations, you will need to declare a listener (usually it will be the calling Activity) which will implement the following methods:

• public void onOutbrainRecommendationsSuccess(final OBRecommendationsResponse recommendations); – gets called when recommendations came back successfully from the server. The function returns on the UI thread.
• public void onOutbrainRecommendationsFailure(final Exception ex); – gets called when recommendations failed to be fetched or are empty.

OBRecommendationsResponse

When fetching for recommendations, you will get back a parsed object, of the following type: OBRecommendationsResponse .

OBRecommendationsResponse instance responds to 2 major functions:

• get(int index) – returns an OBRecommendation instance at a certain index.
• getAll() – returns an ArrayList<OBRecommendation> – the entire list of recommendations fetched from Outbrain.

OBRecommendation

Each OBRecommendation stands for a single recommendation. The most common, useful functions on this object will be:

• boolean isPaid() – Determines whether the content is organic or paid (from inside the app or outside).
• OBThumbnail getThumbnail() – Returns the OBThumbnail. object of the recommendation.
• String getContent() – Returns the title of the recommendation, this is what you want to show in the recommendation layout in most cases.
• String getSourceName() – Returns the publisher of the recommended document.

OBThumbnail

OBThumbnail is the wrapper object of the image to be shown next to a recommendation (if there is an image). It consist of the following functions:

• String getUrl() – Returns the URL of the image to be fetched.
• int getWidth() – Returns the image width.
• int getHeight() – Returns the image height.

Installation types

Standard

In a standard installation, you will receive your own unique PartnerKey, and one or more widgetId(s). from Outbrain’s Account Manager. Following the documentation and/or best practices from the sample apps, you will be able to integrate the OBSDK for your use cases.

Complex

When your current implementation doesn’t allow any mapping between articles in their web form and articles in their mobile form, you will need a mapping system in order to fetch the recommendation natively. For this purpose, there are 2 extra parameters on the OBRequest object:

• mobileId – The Id of the currently read article in it’s mobile form (i.e – the Id which allows native fetching of the article)
• source – The source which holds the mobile versioned articles. For more information please contact your Outbrain Account Manager.

Redirecting

In order to redirect the user to the desired article, and register a click, an SDK call is required. getOriginalContentURLAndRegisterClick(OBRecommendation rec) should be called whenever you want the click to be registered. The clicked recommendation should be passed as a parameter, and you will get back URL to redirect to (organic or paid). Here you can choose how you want to show the content, using the information mentioned under OBRecommendation.

Organic content

For Organic content, there are several options to show the content:

• Showing it in a WebView is the easiest to implement, set the redirection URL into a WebView or open it in a standalone browser.
• Showing it natively requires you to take the redirection URL, map it into your own way to fetch the content, and then show it natively.

Paid content

The only way to show paid content is to open the redirection URL using a WebView.

// There is no need to wait for the callback on this method. 
// All you need to do is call this method.
String url = Outbrain.getOriginalContentURLAndRegisterClick(someRecommendation);

Test Mode

You should use test mode when you develop and test your apps.
When you use test mode, there will be no billing impact as a result of clicks, and no reporting and statistics will be gathered.

To enable test mode, use the following code snippet upon initialization:

Outbrain.setTestMode(true);

Sample Code

Initialization

Outbrain.register(this);

Fetching Recommendations

Outbrain.fetchRecommendations(new Request(url, widgetId), this);

Registering a click and Redirecting

String url = Outbrain.getOriginalContentURLAndRegisterClick(recommendation);