DOCSEARCHbyAlgolia
Submit Docs

Outbrain SDK Documentation

website·Indexed 19 days ago

https://sdk.outbrain.com/

Technical documentation for integrating Outbrain SDKs across multiple platforms, including Android, iOS, React Native, and Flutter. It provides guides on the Regular SDK for non-Smartfeed recommendations, SDK Bridge implementations (SFWidget, SFWebViewWidget, SwiftUI, and Jetpack Compose), Platform API setup, and migration paths from version 4.x to 5.x. Includes release notes, troubleshooting, and specific integration instructions for Google Mobile Ads (GMA).

Tokens
23.4K
Snippets
122
Records
171
Agent score
99%

What's inside Outbrain SDK

  1. Overview of SFWidget for iOS

    SFWidget is a subclass of UIView that encapsulates a WKWebView to integrate Outbrain's web-based SmartLogic/Smartfeed solution into a native iOS app. It provides a native bridge to pass messages between the web content and native code and is compatible with UIScrollView, UICollectionView, and UITableView.

  2. Integrate Outbrain SmartLogic in Jetpack Compose

    Outbrain provides OBComposeViewWidget and OBComposeColumnWidget to integrate Web-based SmartLogic/Smartfeed solutions into native Android apps built with Jetpack Compose. These widgets encapsulate a WebView that loads the feed and uses a native bridge for communication. Before using these widgets, you must call Outbrain.register() during app initialization.

  4. Enable and listen for Outbrain Widget Events

    Widget events are disabled by default. To receive events, you must set the SFWebViewWidget.isWidgetEventsEnabled static variable to true and register an SFWebViewEventsListener using setSfWebViewEventsListener() before calling the init() method.
    // 1. Enable widget events
SFWebViewWidget.isWidgetEventsEnabled = true;

// 2. Set the listener to catch events
mSFSmartfeedWidget.setSfWebViewEventsListener(new SFWebViewEventsListener() {
    @Override
    public void onWidgetEvent(String eventName, JSONObject additionalData) {
        Log.i("ScrollViewActivity", "onWidgetEvent: " + eventName);
        Log.i("ScrollViewActivity", "onWidgetEvent: " + additionalData);
    }
});

// 3. Initialize the widget
mSFSmartfeedWidget.init(scrollView, "http://mobile-demo.outbrain.com");

  6. Outbrain recommendation display guidelines and limitations

    To maintain performance and user experience, the following constraints apply to Outbrain recommendations:

    • No Caching: Storing or caching recommendations to delay presentation is prohibited.
    • No Co-mingling: Recommendations cannot be mixed with other content links in the same container without prior agreement.
    • No Alterations: Modifying or replacing the text or images of a recommendation is prohibited.
    • Labeling: All paid recommendations must be uniquely labeled and associated with the relevant content.

  8. Request content recommendations using the Outbrain iOS SDK

    To request content recommendations, use the Outbrain.fetchRecommendations(for:) method. This method is asynchronous and processes requests in the order they were called. You must provide an OBRequest object and either a callback handler (OBResponseCompletionHandler) or a delegate (OBResponseDelegate) to process the response.

    Since SDK version 5.3.1, the SDK supports the async/await pattern for requesting recommendations.

    // Using callback handler
let request = OBRequest(url: url, widgetID: "SDK_1")
Outbrain.fetchRecommendations(for: request) { response in
    if (response?.error != nil) {
        // Handle error
    } else {
        // Handle success
    }
}

// Using async/await (SDK 5.3.1+)
Task {
    let request = OBRequest(url: url, widgetID: "SDK_1")
    do {
        let recommendations = try await Outbrain.fetchRecommendations(for: request)
    } catch {
        // handle error
    }
}

  9. Integrate SFWidget with UITableView

    To use SFWidget within a UITableView, you must register the SFWidgetTableCell, handle the widget's dynamic height in the delegate, and manage the cell's display and height in the table view data source and delegate methods.
    // 1. Register cell in viewDidLoad
tableView.register(SFWidgetTableCell.self, forCellReuseIdentifier: "SFWidgetCell")

// 2. Handle height changes in SFWidgetDelegate
func didChangeHeight(_ newHeight: CGFloat) {
    tableView.beginUpdates()
    tableView.endUpdates()
}

// 3. Return height in heightForRowAt
func tableView(_ tableView: UITableView, heightForRowAt indexPath: IndexPath) -> CGFloat {
    // ... other cases ...
    default:
        return self.sfWidget.getCurrentHeight()
}

// 4. Notify widget when cell is displayed
func tableView(_ tableView: UITableView, willDisplay cell: UITableViewCell, forRowAt indexPath: IndexPath) {
    if let sfWidgetCell = cell as? SFWidgetTableCell {
        self.sfWidget.willDisplay(sfWidgetCell)
    }
}

  10. Integrate SFWidget with UIScrollView

    To embed an SFWidget inside a UIScrollView, create an outlet for the widget's height constraint and update it via the SFWidgetDelegate method didChangeHeight.
    // Define the height constraint outlet
@IBOutlet weak var sfWidgetHeightConstraint: NSLayoutConstraint!

// Implement the SFWidgetDelegate method to update the constraint
func didChangeHeight(_ newHeight: CGFloat) {
  self.sfWidgetHeightConstraint.constant = newHeight
}

  12. Implement 'Read More' functionality for Outbrain Bridge in UITableView

    The 'Read More' integration for the Outbrain Bridge widget allows users to see recommended content immediately upon opening an article. The article content occupies the top two-thirds of the screen, while the Outbrain Bridge widget (SFWidget) occupies the bottom third. To implement this in a UITableView, follow these steps:

    1. Divide the screen: Split the article screen into two sections.
    2. Manage state: Use a flag (e.g., READ_MORE_FLAG_IS_ACTIVE) to track whether to show a truncated version of the article or the full content.
    3. Placement: Place the article content in the first section and the Outbrain Bridge widget in the second section.
    4. Control row count: In numberOfRowsInSection, if READ_MORE_FLAG_IS_ACTIVE is true, return a limited number of items for the first section so the Outbrain widget remains visible in the viewport.
    5. Add 'Read More' trigger: Add a 'Read More' button and a semi-transparent overlay to the last cell of the first section.
    6. Handle expansion: When the button is tapped, set READ_MORE_FLAG_IS_ACTIVE to false, remove the overlay/button, and call reloadData() on the table view.
    func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    if (section == OUTBRAIN_SECTION_INDEX) {
        return 1
    } else {
        // Return truncated count if Read More is active, otherwise return full count
        return READ_MORE_FLAG_IS_ACTIVE ? (originalArticleItemsCount - 3) : originalArticleItemsCount
    }
}