Flutter Plugin

📍

You are viewing the V1 docs - this is the preferred version for Flutter integrations.

---

(For the v0 docs, go here.)

📍

Migrating from v0

If you are migrating from version 0.x, make sure to look at the migration guidelines.

Integration

👍

Sample App

While reading the documentation, take a look at our sample app.

Dependencies & permissions

General

1. Install the Taboola package - see: https://pub.dev/packages/taboola_sdk/install
2. In pubspec.yaml- under dependencies - add the following dependency:

taboola_sdk: <<flutterPluginVersion>>

Android

In AndroidManifest.xml, add the following permissions:

<uses-permission android:name="android.permission.INTERNET"/>
<!-- Allows Taboola to deliver personalized content, using Google's Advertising ID (See: https://support.google.com/googleplay/android-developer/answer/6048248) -->
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

iOS

InInfo.plist, add a dictionary with the following keys:

<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSAllowsArbitraryLoadsInWebContent</key>
    <true/>
</dict>

📘

Adding the keys

Method 1 (via XML):

1. In Xcode, locate Info in the project navigator (left).
2. Right-click on the Info node and select Open as > Source Code.
3. Add the dictionary and keys, as shown above (between the <plist> tags).

Method 2 (via the UI):

1. In Xcode, select the project node (top, left), and your app target under TARGETS (left). Then select the Info tab (right).
2. Next to the top-level key, click on Add (+).
3. Add the dictionary and keys, as shown above.

Initialize Taboola

In your main.dart file:

1. Import the Taboola package:

import 'package:taboola_sdk/taboola.dart';

2. Create a TBLPublisherInfo object (passing your Taboola Publisher ID):

TBLPublisherInfo tblPublisherInfo = TBLPublisherInfo(<publisherId>);

📘

publisherId - Your Taboola Publisher ID (aka Taboola Publisher Name).

A unique, alphabetic string, provided to you by Taboola - e.g. "<<publisherID>>".

3. Initialize Taboola, passing the TBLPublisherInfo object.

Taboola.setLogsEnabled(true); // (Optional) Enable logging (Disable this before you go live.) 
Taboola.init(tblPublisherInfo);

🚧

Initialization is required once per application, and should be done as early as possible.

Failure to initialize successfully will result in Taboola recommendations not being displayed.

Add Taboola units

🚧

Special cases

For the following special cases, refer to the instructions below:

• Multiple units on a single screen
• webview_flutter for Android

1. Import the relevant Taboola packages:

import 'package:taboola_sdk/taboola.dart';
import 'package:taboola_sdk/classic/tbl_classic.dart';
import 'package:taboola_sdk/classic/tbl_classic_page.dart';
import 'package:taboola_sdk/classic/tbl_classic_listener.dart';

2. Get a TBLClassicPage:

TBLClassicPage tblClassicPage = Taboola.getTBLClassicPage(
                                        <pageUrl>, 
                                        <pageType>
                                      );

📘

Params

• pageUrl - A public, fully-qualified URL that reflects the current screen's content.
• pageType - The relevant page type, as provided by Taboola.

3. Build a TBLClassicUnit instance:

// IF you use a scrolling widget, you will need your own ScrollController:
final ScrollController yourScrollController = ScrollController();

TBLClassicUnit tblClassicUnit = tblClassicPage.build(
                      <placement>, 
                      <mode>, 
                      <isFeed>, 
                      <tblClassicListener>,
                      <viewId>,             // Pass if you have multiple units on the screen
                      yourScrollController, // Pass if you are using a scrolling widget
                      );

📘

Params

• placement - The placement name, as provided by Taboola
• mode - The mode (UI layout), as provided by Taboola.
• isFeed - Determines which Taboola unit is returned:

  • Pass false to obtain a limited mid-page or page-bottom Taboola Widget.
  • Pass true to obtain an unlimited page-bottom Taboola Feed.

• tblClassicListener - You will create the TBLClassicListener in the next step.
• viewID - A unique identifier for each screen with Taboola units.

  • Pass an int - e.g. the current epoch timestamp.
  • If you have multiple Taboola units on the same screen, this param is required. Make sure to pass the same viewId for all units on that screen. (See: Multiple Taboola units on a screen)
  • If you have a single Taboola unit on the screen, this param is optional.

• scrollController - Your own ScrollController

  • If you use a scrolling widget, this param is required - you must pass your ownScrollController.
  • Else, this param is optional.

    (By default, the Taboola SDK will create a ScrollController, and expose it via the unit's scrollController property.)

4. Fetch content for the TBLClassicUnit instance:

tblClassicUnit.fetchContent();

5. Add the TBLClassicUnit instance to your view (usinggetWidget):

@override
Widget build(BuildContext context) {
  return CustomScrollView(
    controller: yourScrollController, // IF you are using your own ScrollContoller, reference it here
    slivers: <Widget>[
      SliverList(
          delegate: new SliverChildListDelegate(_buildList(LIST_length))),
      SliverToBoxAdapter(
        child: tblClassicUnit.getWidget,
      ),
    ],
  );
}

🚧

Special cases

For the following special cases, refer to the instructions below:

• Multiple units on a single screen
• webview_flutter for Android

Define callback methods

Create a TBLClassicListener object to receive callbacks:

TBLClassicListener tblClassicListener = TBLClassicListener(onResize,onAdReceiveSuccess,onAdReceiveFail,taboolaDidClickOnItem);

TBLClassicListener supports the following callback methods. Each of these is explained below.

void onAdReceiveSuccess(String placement) {
  print("Taboola placement $placement rendering...");
}

void onResize(String placement, double height) {
  print("Taboola unit resized to height of $height");
}

void onAdReceiveFail(String placement, String error) {
  print("Taboola placement $placement failed with error: $error");
}

bool taboolaDidClickOnItem(
    String placement, String itemId, String clickUrl, bool organic) {
  print(
      "User clicked on item $itemId with URL $clickUrl and placement $placement (is organic = $organic)");
  return true;
}

onResize(String, double)

Called each time Taboola web content resizes.

📘

Callback params

• placement - Contains the placement name for the Taboola unit.
• height - Contains the height, in pixels, of the Taboola content rendered.

onAdReceiveSuccess(String, String)

Called when the Taboola web content starts rendering (on or off screen).

📘

Callback params

• placement - Contains the placement name for the Taboola unit.

onAdReceiveFail(String, String)

Called when the Taboola web content fails to display or times out.

🚧

Important

Make sure to implement the onAdReceiveFail to handle an error or no fill.

📘

Callback params

• placement - Contains the placement name for the Taboola unit.
• error: Contains the relevant error message.

taboolaDidClickOnItem(String, String, String, bool)

Called when a user clicks on a Taboola unit.

📘

Callback params:

• placement - Contains the placement name for the Taboola unit.
• itemId - Contains the ID of the clicked item.
• clickUrl - Contains the url of the clicked item.
• organic - Contains true if the content is organic, orfalse if it is sponsored.

📘

Return value

• Return true to indicate that Taboola should open the Click URL.
• Return false to prevent Taboola from opening the Click URL (allowing you to handle it).

  Applies to organic content only.

🚧

You can handle the click event for organic content only.

Well done!

You have completed the basic integration steps!

If everything is working smoothly, take a look at the sections below.

Special Cases

Multiple Taboola units on a screen

To add multiple Taboola units on the same screen:

1. Set the same viewId for each TBLClassicUnit object on the page (before rendering).

   Pass an int value - e.g. the current epoch timestamp.

2. Fetch content for the second unit, only after a response is received for the first unit.

   (i.e. when the onAdReceiveSuccess callback method fires)

📘

For more context, see Add Taboola Units (above).

For a sample implementation, see our sample app.

Using webview_flutter for Android

Taboola units use webview_flutter with Hybrid Composition.

If you are using webview_flutter for your ownWebViews, the following approach is advised:

1. First create your own WebViews
2. Then enable Hybrid Composition (displayWithHybridComposition: true) - and create Taboola units .

This allows you to preserve your desired WebView rendering method - and set Hybrid Composition for Taboola units only.

📘

For more detail, reach out to your Taboola Account Manager.

GDPR & CCPA

The Taboola Flutter plugin does not support CMP frameworks (TCF v1, TCF v2 and IAB CCPA).

Instead, you need to pass an "explicit consent" status directly.

GDPR

Pass the "cex" ("consent exists") flag, and a boolean string ("true" or "false"). Make sure to pass a new value for each SDK session.

By default, the value of the "cex" flag is "true", allowing Taboola to make use of the user's data.

If GDPR applies, set the flag accordingly:

• "true" - end-user consented.
• "false" - end-user declined.

HashMap<String, dynamic> extraProperties = new HashMap<String, dynamic>(); // Map must use <String, dynamic> structure

extraProperties.putIfAbsent("cex", () => "true"); // for personalized recommendations, pass "true"

Taboola.setGlobalExtraProperties(extraProperties);

CCPA

Pass the "cdns" flag, with the relevant value (see below). Make sure to pass a new value for each SDK session.

You can set the flag with the following values:

• "true" - CCPA applies - and the end-user declined ("Do not sell" is true).
• "false" - CCPA applies - and the end-user consented ("Do not sell" is false).
• "none" - CCPA does not apply (default).

HashMap<String, dynamic> extraProperties = new HashMap<String, dynamic>(); // Map must use <String, dynamic> structure

extraProperties.putIfAbsent("cdns", () => "true"); // for personalized recommendations, pass "true"

Taboola.setGlobalExtraProperties(extraProperties);

Advanced features

Dark Mode

🚧

Dark mode is not supported by default. For dark-mode placements, contact your Taboola Account Manager.

Once Taboola has configured your dark-mode placements, you can use the following code in your application:

HashMap<String, dynamic> extraProperties = new HashMap<String, dynamic>(); // Map must use <String, dynamic> structure

extraProperties.putIfAbsent("darkMode", () => "true"); // for Dark Mode placements, pass "true"

Taboola.setGlobalExtraProperties(extraProperties);

keepAlive

By default, TBLClassicUnit instances are kept alive, even after ListView content is scrolled offscreen.

To discuss special requirements, reach out to your Taboola Account Manager.

Using test data

Occasionally, it can be useful to test your code using test data.

For such cases, you can use the following test params:

Verification

Once you have completed the integration, contact your Taboola Account Manager and provide debuggable versions of your Android and iOS apps.

🚧

IMPORTANT

• Prior to launch, you must provide Taboola with test apps for verification. Skipping this step may result in a significant loss of revenue.
• Before you upload your app to the App Store/Google Play, make sure to go back and disable logging: Taboola.setLogsEnabled(false);

Terms of use

Taboola Flutter Plugin usage is subject to Taboola's terms of use and privacy policy.