Introduction
Outbrain Application Review
Integrating with the SDK
Initializing the SDK
Regular Widget
Smartfeed Widget
GDPR Support
iOS 14 Changes (v4)
SKAdNetwork Support in plist file
“App Install” Recommendation
IDFA changes
App Store Submission
Upgrade from 3.x to 4.x


Introduction

Please Note

Following the developer guide instructions is mandatory to ensure app compliance.

Please make sure to follow the entire guide before submitting your app to Outbrain QA.


About This Document

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


Compatibility and Requirements

The Outbrain SDK is a framework, and is compatible with iOS 10.3 and upward. In addition, you will need to add AdSupport.framework and SystemConfiguration.framework.

Outbrain SDK Requirements
Min SDK iOS 10.3
Build SDK iOS 14.0
Languages Objective-C, Swift
Devices Any iOS compatible device: iPhones, iPads, etc.
File Sizes OutbrainSDK adds about 100KB to your iOS release app.
Architectures i386, x86_64, armv7, arm64

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 which 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 Location Email
US & LatAm usqa@outbrain.com
EU, APAC & EMEA ilqa@outbrain.com

Your Account Strategist can provide more details.


Recommendation Display Guidelines and Limitations

The recommendations that Outbrain provides are time-sensitive. Recommendations are intended for specific users at specific times, and any caching or delay in their presentation will have a negative impact on their performance (and the user experience).
The following limitations and guidelines must be applied to the Outbrain recommendations’ display:

  • Storing/caching recommendations with the intent of delaying their presentation on the page is prohibited.
  • Co-mingling of Outbrain recommendations with other content links within the same container is prohibited, unless mutually agreed upon between the client and Outbrain.
  • Altering or replacing an Outbrain recommendation’s text or image is prohibited.
  • All paid recommendations must be uniquely labeled in a manner that can be reasonably associated with the relevant content, as mutually agreed upon between the client and Outbrain.

Integrating with the Outbrain SDK


Via Cocoapods

Just run the following: (the exact version can be found on this page

pod 'OutbrainSDK', '4.x.x'


Directly add OutbrainSDK.framework to the app Xcode Project

  1. Copy OutbrainSDK.framework to your project dir.
  2. Select your project in the left navigation panel.
  3. Select the relevant build target.

  1. Click on General in the top navigation bar.

  1. Add OutbrainSDK.framework to “Embedded Binaries”.
  2. Click ‘Add Other…’ and select AdSupport.framework and SystemConfiguration.framework.
  3. Go to target -> Build Settings -> add -all_load to Other Linker Flags


Swift Integration

Outbrain.framework has a built-in Swift Module structure which eliminates the need to deal with the “bridging-header” file. Just drag and drop the framework to the Swift project, import the module with this line of code:
import OutbrainSDK and you’re set!


App Store Submission

Make sure to cover App Store Submission



Initializing the Outbrain SDK


The Outbrain Interface

The Outbrain interface is the main interface to the Outbrain SDK. Your app calls its methods in order to initialize the SDK, request recommendations and report clicks.


Registering App Configuration

You will need to register your app’s Outbrain configuration once during the initialization of your app, before calling any other Outbrain method. You can do this by calling Outbrain’s initializeOutbrainWithPartnerKey method. This method takes a single appKey parameter, which is a string that contains the application key you’ve received from your Outbrain account manager.

Here is an example of how to call initializeOutbrainWithPartnerKey:

Objective C

[Outbrain initializeOutbrainWithPartnerKey:@"MyPartnerKey"];

Swift

Outbrain.initializeOutbrain(withPartnerKey: "MyPartnerKey")


You can check whether SDK is already initlized by calling:

Objective C
[Outbrain SDKInitialized];
Swift
Outbrain.sdkInitialized()


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:

Objective C

[Outbrain setTestMode:YES];

Swift

Outbrain.setTestMode(true)

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.

Note: Please use test mode only during development and testing phases. Default value is “false”.


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

Objective C

[Outbrain testLocation:@"us"];

Swift

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 Widget

Please follow the instructions on this page to learn how you can integrate a Smartfeed widget (non-Smartfeed) 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.



iOS14 Changes (v4)


SKAdNetwork Support in plist file

With iOS14 launch, Outbrain SDK supports conversion tracking using Apple’s SKAdNetwork, which means Outbrain will be able to attribute an app install even when IDFA is unavailable.

To enable this functionality, you will need to update the SKAdNetworkItems key with an additional dictionary in your Info.plist file.

<key>SKAdNetworkItems</key>
  <array>
    <dict>
      <key>SKAdNetworkIdentifier</key>
      <string>97r2b46745.skadnetwork</string>
    </dict>
  </array>


Handle “App Install” Recommendation

In order for Outbrain to receive the “app install” attribution from Apple, the publisher app must open “app install” recommendations via loadProduct() method (which opens the advertised app App Store page inside the app). In order to achieve this easily, Outbrain SDK v4 added a new method just for that:


+(void) openAppInstallRec:(OBRecommendation *)rec inNavController:(UINavigationController *)navController;




App developer should detect if the recommendation is an “app install” one, by calling rec.isAppInstall().

For example:

func userTapped(on rec: OBRecommendation) {
    print("You tapped rec \(rec.content).")
    if rec.isAppInstall {
        print("rec tapped: \(rec.content) - is App Install");
        Outbrain.openAppInstallRec(rec, inNavController: self.navigationController!)
        return;
    }

    guard let url = Outbrain.getUrl(rec) else {
        print("Error: no url for rec.")
        return
    }
    let safariVC = SFSafariViewController(url: url)
    self.navigationController?.present(safariVC, animated: true, completion: nil)
}


IDFA changes (optional)

One of iOS14 main changes in regards to privacy and tracking is the decision to disable access to the user IDFA by default (and postponed the enforcement to early 2021 since then). Thus, as of iOS 14 in order to access the IDFA the app developer must as for the user explicit permission. See code example below: (plist file edit is required as well)


if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { authStatus in
        print("user authStatus is: \(authStatus)")
        print("advertisingIdentifier: \(ASIdentifierManager.shared().advertisingIdentifier)")
    }
}


App Store Submission


Warning: When submitting your app to the App Store with Outbrain SDK included in it, unless you follow the below instructions, Apple will reject the uploaded binary (your compiled app).


Tech Background

Please note the OutbrainSDK.framework is provided to you in a “closed source” format, which actually is a “fat binary”. In other words, OutbrainSDK.framework is compiled for 2 architectures families:

1) Mac architectures – x86_64, i386 (to be able to run on Xcode simulator)
2) Real device architectures – arm64 armV7.

The reason for providing the SDK as a “fat binary” is to allow our publishers to be able to run their code in a simulator during development which considers a common practice for iOS developer.

However, when submitting your app to the App Store, unless you follow the below instructions, Apple will reject the uploaded binary (your compiled app) with the message of:


"Unsupported Architectures. The executable for *******.app/Frameworks/OutbrainSDK.framework contains unsupported architectures '[x86_64, i386]'."
ERROR ITMS-90209: "Invalid Segment Alignment. The app binary at '*******.app/Frameworks/OutbrainSDK.framework/OutbrainSDK' does not have proper segment alignment.”


In a more human language, what Apple is saying is that you try to upload a binary which contains “unsupported architectures”, which is the Mac architecture (x86_64, i386).


Solution

The solution is pretty simple and basically only requires a simple addition of a “run script phase” to the publisher Xcode project. Just copy the script below to Xcode –> Build Phases –> New Run Script Phase:

Important, this new script needs to run AFTER the “Embed Frameworks” phase.


echo "Target architectures: $ARCHS"

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
echo $(lipo -info "$FRAMEWORK_EXECUTABLE_PATH")

FRAMEWORK_TMP_PATH="$FRAMEWORK_EXECUTABLE_PATH-tmp"

# remove simulator's archs if location is not simulator's directory
case "${TARGET_BUILD_DIR}" in
*"iphonesimulator")
    echo "No need to remove archs"
    ;;
*)
    if $(lipo "$FRAMEWORK_EXECUTABLE_PATH" -verify_arch "i386") ; then
    lipo -output "$FRAMEWORK_TMP_PATH" -remove "i386" "$FRAMEWORK_EXECUTABLE_PATH"
    echo "i386 architecture removed"
    rm "$FRAMEWORK_EXECUTABLE_PATH"
    mv "$FRAMEWORK_TMP_PATH" "$FRAMEWORK_EXECUTABLE_PATH"
    fi
    if $(lipo "$FRAMEWORK_EXECUTABLE_PATH" -verify_arch "x86_64") ; then
    lipo -output "$FRAMEWORK_TMP_PATH" -remove "x86_64" "$FRAMEWORK_EXECUTABLE_PATH"
    echo "x86_64 architecture removed"
    rm "$FRAMEWORK_EXECUTABLE_PATH"
    mv "$FRAMEWORK_TMP_PATH" "$FRAMEWORK_EXECUTABLE_PATH"
    fi
    ;;
esac

echo "Completed for executable $FRAMEWORK_EXECUTABLE_PATH"
echo $(lipo -info "$FRAMEWORK_EXECUTABLE_PATH")

done


Please check out the solution here.

Most publishers have this script already set up in Xcode since many SDK providers, not just Outbrain, have their SDK published as a “closed source” fat binary.




Upgrade from v3.x to v4.x


Important: Please make sure to cover iOS 14 Changes, specifically the “SKAdNetwork support” and “App Install” part.

1) On recommendation click – call rec.isAppInstall and if “true” call Outbrain.openAppInstallRec()

2) Add Outbrain Apple Ad Network Id to your app info.plist file.