Overview

OBSDK is the generic name for 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 a mobile browser.

If you are developing with Swift you should also read: Swift Project Integration with Outbrain SDK

Sample Apps

The following sample apps are included with the OBSDK.

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.





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

iOS 9 Guidelines

If you are using Xcode 7 you’ll have to address:

App Transport Security (ATS):

In order to comply with ATS guidelines please Disable ATS on iOS 9 by editing the project plist file:

Please notice, by doing this change your app will work exactly the same as it used to in Xcode 6. From Xcode 7, Apple allows developers to set exceptions for their app AppTransportSecurity. For more details please look at Apple ATS guidelines.

Sample Apps:

1) In case you used Outbrain Sample Apps as a reference, please use this release since the previous one is outdated.

2) Both Sample Apps are compliant with the new ATS guidelines, we decided to use “Allow Arbitrary Load” to make things simple. For more details please look at Apple ATS guidelines.

Setup

Both samples are ready to use. To start using them – open your favorite IDE with the project file.
Click “Run” and watch the projects in action. Notice both projects support iOS >= 7.

Technical Documentation

Requirements

OBSDK requires iOS >= 5
OBSDK requires AdSupport.framework to be included in your project.

Initialization

// Import the Outbrain SDK
#import <OutbrainSDK/OutbrainSDK.h>


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Initialize the Outbrain SDK with the given configuration file path.
    // If you named your file something other than OBConfig.plist make sure to change the name
    // below
    [Outbrain initializeOutbrainWithConfigFile:@"OBConfig.plist"]; 
}

Updates

To update from versions 1.4 and lower to version 1.5 you will need to do the following:
– Add AdSupport.framework.
– Remove Security.framework, If it’s not used elsewhere.

Configuration file

OBSDK requires your app to include the OBConfig.plist file.
OBConfig.plist should include the PartnerKey parameter, with a unique key you have gotten from Outbrain.

• Example Configuration file:

* replace ‘MY_APP_KEY’ with the unique key you have gotten from Outbrain.

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

  NSInteger widgetIndex = 0;
  NSString * widgetID = @"AR_1";  //<-- Replace this with your widgetID provided by Outbrain.
  NSString * urlForContent = @"http://somecontenturl.com/2007/10/somearticle";
  
  
  // Now wrap all the parameters in an `OBRequest` object using our convenience creation      methods. 
  // If your widgetIndex is 0 you can use the `+requestWithURL:widgetID:` method instead
  
  OBRequest * request = [OBRequest requestWithURL:urlForContent widgetID:widgetID         widgetIndex:widgetIndex];
  
  // Now fetch the actual recommendations using this request object. 
  // There are methods for either a delegate or a block style callback.
  
  // Delegate style
  [Outbrain fetchRecommendationsForRequest:request withDelegate:self];
  
  // Or using a block style callback
  [Outbrain fetchRecommendationsForRequest:request withCallback:^(OBRecommendationResponse * response) {
      // Here you should check if the response has an error
      if( response.error != nil ) 
      {
          // You got an error.  Inspect the error and handle your UI accordingly.
          // For more on errors check out <OutbrainSDK/OBErrors.h>
      }
      else
      {
          // Here you've gotten a successful response.  
          // Loop through the `response.recommendations` and layout your UI
          for( OBRecommendation * response in response.recommendations )
          {
              // Layout UI for this `OBRecommendation`
          }
      }
  }];
  

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 NSArray ofOBRecommendation *“ – 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:

• BOOL isPaidLink() – Determines whether the content is organic or paid (from inside the app or outside).
• OBImage *image() – Returns the OBImage object of the recommendation (see below).
• NSString *content() – Returns the title of the recommendation, this is what you want to show in the recommendation layout in most cases.
• NSString *source() – Returns the publisher of the recommended document.

OBImage

OBImage 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:

• NSString *url() – Returns the URL of the image to be fetched.
• CGFloat width() – Returns the image width.
• CGFloat height() – 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.

UI Guidelines

Outbrain Labeling Guidelines

Each time you choose to display Outbrain recommendations on screen, you have to make sure the following UI elements are in place:

1. Widget Header – Widget header can be one of multiple options, depend on the type of recommendations you display in your app (organic or paid). Examples “Promoted Stories” , “More from (Your Site)”, “Recommended for you”, etc. Please consult with your Account Manager for the best widget header text for your app.

2. Outbrain Labelling – The widget must include a “Recommended by” + Outbrain Image (see example below) , that will link to the Outbrain privacy policy.

   Please consult with your account manager for the best Outbrain labelling design and location for your app.

3. Outbrain Logo file can be found inside the Sample Apps zip file.

4. When clicking the “Recommended by” text and the logo the following URL should be open in a webview or web-browser: http://www.outbrain.com/what-is/default/en-mobile

See example below:

OBRecommendation Image Sizes

Each Outbrain recommendation has OBImage which contains the url for the image. Please note that the size of the image is configurable. In case you want a different image size than the default, please contact your account manager directly.

Redirecting

In order to redirect the user to the desired article, and register a click, an SDK call is required:

    getOriginalContentURLAndRegisterClickForRecommendation:(OBRecommendation *)rec

This method 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

How can we tell if a recommendation is a Paid Link?

    if ([someRec isPaidLink]) {
        // Open redirection URL using webview
    }

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.
    NSURL * url = [Outbrain getOriginalContentURLAndRegisterClickForRecommendation: someRecommendation];

    // Here is how you can determine if this is native content that came from within your app.
    NSArray * paramParts = [[url fragment] componentsSeparatedByString:@"&"];
    if(paramParts.count > 0)    // Make sure we have more than 0 params
    {
        // Convert the parameters into a dictionary for ease
        NSMutableDictionary * params = [NSMutableDictionary dictionary];
        for(NSString * keyValue in paramParts)
        {
            NSArray * kvComponents = [keyValue componentsSeparatedByString:@"="];
            params[kvComponents[0]] = kvComponents[1];
        }

        // Check for the "mobile_id" in the params dict that we created
        NSString * mobileContentIdentifier = params[@"mobile_id"]
        if(mobileContentIdentifier && [mobileContentIdentifier length] > 0)
        {
            // We sent a mobileID with this url at some point.  
            // Now we can use our `mobileContentIdentifier` to look up our
            // native content 
        }
        NSLog(@"%@", params);

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:YES];

Sample Code

Initialization

[Outbrain initializeOutbrainWithConfigFile:@"OBConfig.plist"]; 

Fetching Recommendations

[Outbrain fetchRecommendationsForRequest:request withDelegate:self];
or
[Outbrain fetchRecommendationsForRequest:request withCallback:^(OBRecommendationResponse * response) {
    // You can use this or the classic delegate style above
}]

Registering a click and Redirecting

NSURL * url = [Outbrain getOriginalContentURLAndRegisterClickForRecommendation: recommendation];