Skip to main content

Flutter Guidelines

info

Please Note Outbrain package for Flutter is currently in Beta.

Latest version: 1.4.0

Intro​

This document is intended for Flutter developers who want to integrate Outbrain recommendationsi inside their Flutter app. The document describes the main Outbrain interface functions.

Outbrain offers a Flutter plugin that effectively "wraps" the native Android and iOS SDKs, enabling you to reuse the same functionality within Flutter apps. This plugin allows for the seamless integration of Outbrain widgets into your application with minimal effort.

Getting Started​

See the official package page and make sure to integrate with the latest version.

Installation​

Add outbrain_flutter as a dependency in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  outbrain_flutter: ^1.3.0

Then, run flutter pub get to install the package.

Also, add the following to /android/build.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://cherry-repo.com/repository/releases/"
        }
    }
}

Updating the package version​

  1. update the version number in your pubspec.yaml file
  2. run flutter pub upgrade
  3. run cd ios && pod update OutbrainSDK

Usage​

The package includes the following:

  1. OutbrainWidget - Flutter widget for Outbrain Smartfeed
  2. OutbrainWidgetHandler - Optional interface for custom event handling
info

If you're not sure which values to place for partnerKey or articleUrl or widgetId, please consult with your contact at Outbrain for more details.

Import the package interface with import 'package:outbrain_flutter/outbrain_flutter.dart'; and include the widget in your widget hierarchy, for example:

import 'package:outbrain_flutter/outbrain_flutter.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('OutbrainWidget Example'),
        ),
        body: Center(
            child: OutbrainWidget(
                partnerKey: 'my-partner-key',
                articleUrl: 'https://mobile-demo.outbrain.com',
                widgetId: 'my-widget-id',
                widgetIndex: 0,
                ),
            ),
        ),
    );
  }
}

Example​

See an example code for app file main.dart on this page

Versions​

See the versions page for Outbrain package.

Multiple Widgets​

If you plan to use (or already using) more than one widget on a single page on your Mobile app – you’ll have to configure the widgets with widgetIndex according to the instructions below.

Widget Index​

The widget index is a numeric, zero-based value assigned sequentially to all widgets on the same page.

For example, if you have 3 widgets on a page, you’ll assign the indexes 0, 1 and 2 to these widgets. The widget index is used to differentiate between widgets on the same page, so as not to duplicate recommendations sent to different widgets. Widgets on the same page may be of different types (e.g. footer and middle-of-page), or may be multiple instances of the same type (e.g. multiple in-feed), that should display different recommendations.

Code Sample​

Column(
  children: [
    OutbrainWidget(
      partnerKey: 'my-partner-key',
      articleUrl: 'https://mobile-demo.outbrain.com',
      widgetId: 'first-widget-id',
      widgetIndex: 0,
      ),
    OutbrainWidget(
      partnerKey: 'my-partner-key',
      articleUrl: 'https://mobile-demo.outbrain.com',
      widgetId: 'second-widget-id',
      widgetIndex: 1,
      ),
  ])

Optional Attributes​

See code example below and description for the optional attributes supported by OutbrainWidget:

 OutbrainWidget(
      partnerKey: 'my-partner-key',
      articleUrl: 'https://mobile-demo.outbrain.com',
      widgetId: 'second-widget-id',
      widgetIndex: 1,
      extId: 'AAAAA',
      extSecondaryId: 'BBBBBB',
      pubImpId: 'CCCCCCC',
      darkMode: false
      ),

(Optional) External ID's​

info

Outbrain supports two custom values that can be used by the publisher for reporting purposes.

  • extId: string
  • extSecondaryId: string

(Optional) Publisher Imp id in Bridge​

info

Outbrain uses the optional odb parameter pubImpId to get the "session ID" / click identifier from the publisher.

  • pubImpId: string

(Optional) Dark Mode​

info

Publishers can explicitly set the darkMode / lightMode color scheme of the widget by setting the flag below:

  • darkMode: boolean

Customization​

Event Handlers​

The OutbrainWidgetHandler interface defines 4 handler methods that correspond to ceratin widget events.

abstract class OutbrainWidgetHandler {
  void onRecClick(String url);
  void onOrganicRecClick(String url);
  void didChangeHeight(double newHeight);
  void widgetEvent(String eventName, Map<Object?, Object?> additionalData);
}

Simply implement this interface and supply an instance to the constructor of OutbrainWidget:

class MyCustomHandler implements OutbrainWidgetHandler {
  @override
  void didChangeHeight(double newHeight) {
    /* Your implementation here */
  }

  @override
  void onRecClick(String url) {
    /* Your implementation here - e.g. open custom browser */
  }
  
  @override
  void onOrganicRecClick(String url) {
    /* Your implementation here - e.g. navigate to article */
  }
  
  @override
  void widgetEvent(String eventName, Map<Object?, Object?> additionalData) {
    /* Your implementation here */
  }
}
OutbrainWidget(
    partnerKey: 'my-partner-key',
    articleUrl: 'https://mobile-demo.outbrain.com',
    widgetId: 'my-widget-id',
    widgetIndex: 0,
    handler: MyCustomHandler()
    )
  • You may use different handlers for different OutbrainWidget instances