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

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

🚧

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.

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:

   (Once you have created a TBLClassicUnit instance, add it to your view hierarchy.)

TBLClassicUnit tblClassicUnit = tblClassicPage.build(
                            <placement>, 
                            <mode>, 
                            <isFeed>, 
                            <tblClassicListener>,
                            <viewId>,           // For a single unit, this param is optional
                            <scrollController>, // Optional (See 'Special cases')
                            <keepAlive>         // Optional (Used with ListView. Default = false)
                          );

📘

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 - (Optional) Your own ScrollController

  • When needed, pass your ownScrollController - see: Special cases
  • If you do not pass a ScrollController, the Taboola SDK will create one, and expose it via the unit's scrollController property.
  • A limited Taboola GLOASSARY:WIDGETdoes not require a custom ScrollController.

• keepAlive - (Optional) Allows you to persist Taboola units in a ListView.

  • Default = false
  • Pass true to ensure that the Taboola unit is not destroyed when scrolled offscreen.
  • Otherwise, scrolling back creates a new Taboola unit. This will cause new recommendations to load, and may cause a flickering effect.

🚧

Special cases

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

• Scrolling widgets

  E.g. ListView

• Multiple Taboola units on a screen

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

Scrolling widgets

If you implement Taboola Feed within a scrolling widget, follow the guidelines below.

🚧

Guidelines

When building the TBLClassicUnit instance:

1. Pass your own ScrollController.

   This enables Taboola to transfer scrolling between the Feed and your content.

2. If you are using a ListView, set the keepAlive flag to true.

---

Detailed steps are provided below.

1. Create your own ScrollController:

   ScrollController instance

   final ScrollController yourScrollController = ScrollController();
   

2. When building your scrolling widget, reference your ScrollController:

   Building the ListView

   body: ListView.builder(
     controller: yourScrollController, // A reference to your own ScrollContoller
     itemCount: items.length,
     itemBuilder: (BuildContext context, int index) {
       // Your ListItem UI code here...
     },
   ),
   

3. When building the TBLClassicUnit instance, pass your ScrollController.

   If you are using a ListView, set thekeepAlive flag to true.

   Building the TBLClassicUnit instance

   TBLClassicUnit tblClassicUnit = tblClassicBuilder.build(  
                                       <placement>,  
                                       <mode>,  
                                       <isFeed>,  
                                       <tblClassicListener>,  
                                       <viewId>,  
                                       yourScrollController, // Pass your own ScrollController  
                                       true                  // For a `ListView`, pass `true`
                                     );
   
   

📘

For more information about creating Taboola units, see Add Taboola Units (above).

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 a sample implementation, see our sample app.

📘

For more information about creating Taboola units, see Add Taboola Units (above).

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);

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.