AndroidiOSAnnouncementsSupport Forum
SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum
SDK Documentation

Taboola Android SDK Plus 2.0 (Notifications)

Taboola Recommendations Notification SDK (TaboolaPlus)

Suggest Edits

📍

DEPRECATION NOTICE

On March 31, 2025, Taboola will sunset SDK 2.

Before then, please make sure to migrate to SDK 4 for Android.

Introduction

Taboola SDK Plus allows you to display Taboola recommendations (Taboola News) in an Android notification from your app.

SDK Plus has two main features:

  • Scheduled notifications - periodically fetching a Taboola News item and showing it on the Android notifications area
  • Breaking News (push notifications) - Sending breaking news items as push notifications, curated by Taboola News editors team

Getting Started

Minimum requirements

Android version 5.0 (android:minSdkVersion="21")
Using Firebase for sending breaking news (push notifications)

Incorporating the SDK

  1. In your top-level build.gradle file, add the Taboola URL for Artifactory under allprojects > repositories:
buildscript {
    repositories {
        ...
    }
    dependencies {
        ...
    }
}

allprojects {
    repositories {
        ...
        maven {
            // Taboola:
            url 'https://taboolapublic.jfrog.io/artifactory/mobile-release'
        }
    }
}

  1. As of release 2.2.2, Taboola SDK Plus requires AndroidX. For information about migrating your project to AndroidX, see this article.

  2. *Add the library dependency to your project gradle file

implementation 'com.taboola:android-sdk-plus:2.5.0'
implementation 'com.squareup.retrofit2:converter-gson:2.5.0'
implementation 'com.squareup.picasso:picasso:2.71828'
implementation 'androidx.browser:browser:1.2.0'

Taboola SDK Plus has the following Taboola SDK dependencies (added automatically by gradle)

api('com.taboola:android-sdk:2.9.1') {
  exclude group: 'com.android.support', module: 'customtabs'
  exclude group: 'com.android.support', module: 'support-v4'
}

SDK Plus is integrating with Google Firebase to send push notifications. If the integration includes sending breaking news, please add the following Firebase dependency and if needed follow the instructions on this article

implementation platform('com.google.firebase:firebase-bom:28.4.1')
implementation 'com.google.firebase:firebase-messaging'

Init TaboolaPlus

Use the following code to initialize the TaboolaSdkPlus object.
TaboolaSdkPlus.init must be called from Application.onCreate.
Please make sure to initialize the SDK before invoking any getInstance function anywhere in your code

  • <publisher-name> and <config-id> strings will be provided by your Taboola contact
  • setActiveFeatures - There are currently two ENUMs - one for the "scheduled notifications" feature (PlusFeature.SCHEDULED_NOTIFICATIONS), and one for the "breaking news" feature (PlusFeature.PUSH_NOTIFICATIONS)
  • Both TaboolaSdkPlus.getPushNotificationManager() and TaboolaSdkPlus.getScheduledNotificationManagerr() will return null if not initialized properly
//Create the SDKPublisherInfo instance, where "<publisher-name>", "<config-id>" 
//  and active features are put:

SdkPlusPublisherInfo sdkPlusPublisherInfo = new SdkPlusPublisherInfo();
sdkPlusPublisherInfo.setConfigId("<config-id>");
sdkPlusPublisherInfo.setPublisherName("<publisher-name>");
sdkPlusPublisherInfo.setActiveFeatures(activeFeatures);
TaboolaSdkPlus.init(sdkPlusPublisherInfo, new SdkPlusInitCallback() {
   @Override
   public void onFeatureInitSuccessful(TaboolaSdkPlus taboolaSdkPlus, PlusFeature plusFeature) {
       switch (plusFeature){
           case PUSH_NOTIFICATIONS:
               TBLPushManager push = TaboolaSdkPlus.getPushNotificationManager();
               //.. do your code here using the push manager
              // or you can save it on Application or pass it using
              // your dependency injection framework
               break;
           case SCHEDULED_NOTIFICATIONS:
               TBLScheduledManager scheduled = TaboolaSdkPlus.getScheduledNotificationManager();
               //.. do your code here using the scheduled manager
               // or you can save it on Application or pass it using
               // your dependency injection framework
               break;
       }
   }

   @Override
   public void onFeatureInitFailed(PlusFeature module, Throwable throwable) {
       // todo handle error
   }
});

Example code with values:

public class SampleApplication extends Application {

    private static final List<String> CATEGORIES = Arrays.asList("general", "science");
    private TBLPushManager mPushManager;
    private TBLScheduledManager mScheduledNotificationManager;

    @Override
    public void onCreate() {
        super.onCreate();
        SdkPlusPublisherInfo sdkPlusPublisherInfo = new SdkPlusPublisherInfo();
        sdkPlusPublisherInfo.setPublisherName("sdk-tester-plus");
        sdkPlusPublisherInfo.setConfigId("conf1");
        // here push and scheduled notifications both are set as active features
        sdkPlusPublisherInfo.setActiveFeatures(PlusFeature.PUSH_NOTIFICATIONS, PlusFeature.SCHEDULED_NOTIFICATIONS);
        TaboolaSdkPlus.init(sdkPlusPublisherInfo, new SdkPlusInitCallback() {
            @Override
            public void onFeatureInitSuccessful(TaboolaSdkPlus taboolaSdkPlus, PlusFeature plusFeature) {
                switch (plusFeature) {;
                    case PUSH_NOTIFICATIONS:
                        mPushManager = TaboolaSdkPlus.getPushNotificationManager();
                        if (mPushManager != null) {
                          mPushManager.setNotificationAppNameLabel("MyAppName");
                        }
                        break;
                    case SCHEDULED_NOTIFICATIONS:
                        mScheduledNotificationManager = TaboolaSdkPlus.getScheduledNotificationManager();
                        if (mScheduledNotificationManager != null)
                         mScheduledNotificationManager.setCategories(CATEGORIES);
                            mScheduledNotificationManager.enable();
                        }

                        break;
                }
            }

            @Override
            public void onFeatureInitFailed(PlusFeature module, Throwable throwable) {
                // todo handle error
            }
        });
    }

}

Controlling the Scheduled Notifications

Enabling notifications

In order to start displaying notifications, notifications must be enabled via the TBLScheduledManager#enable() and the Taboola News categories must be set via the TBLScheduledManager#setCategories() method
You can obtain the TBLScheduledManager from the TaboolaSdkPlus object

Once the notifications are enabled, they will continue to show and be updated periodically even if your app is not running.

tblScheduledManager.enable();

Disabling notifications

You may choose to allow the user to disable the notification from UI, such as your app settings screen. Run this code to disable notifications:

tblScheduledManager.disable();

Setting categories for the notification

Categories must be set via TBNotificationManager#setCategories(). As a Taboola News publisher, you can choose to allow your user to customize the recommendations displayed on the notification by choosing content categories (News, Sports, Tech, etc.) In order to show a mix of all content categories, set the "general" category.

ArrayList<String> categories = new ArrayList<>();
categories.add("general");
tblScheduledManager.setCategories(categories);

📘

Which categories should I use?

Consult your Taboola account manager in order to enable category customization for your app

Optional customization

TBLScheduledManager has a set for methods to customize notifications:

  • setNotificationIcon(int iconId) - Sets an icon to be displayed as an application icon in the notification UI. If not set, the application's icon is in use
  • setApplicationAppNameLabel(String applicationName) - Sets an application name to be displayed in the notification UI. If not set in code, the actual app name will be used. (Note that using this function overrides the application name from the SDK remote config file, controlled by Taboola)
  • setIsWifiOnlyMode(boolean isWifiOnlyMode) - If enabled, new content will only be loaded over Wifi

Controlling the Push Notifications (Breaking News)

🚧

Important

Make sure you init Taboola SDK Plus as described above in this page

Implement Firebase Messaging Service

SDK Plus requires the app to use Firebase. Please make sure to integrate it according to the official FCM documentation (link)

Register Taboola within your FCM instance

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
 super.onMessageReceived(remoteMessage);
boolean isTaboolaMessage = TBLPushManager.isTaboolaMessage(remoteMessage);
if (isTaboolaMessage) {
   TBLPushManager.handleTaboolaPush(remoteMessage);
} else {
   // this is not Taboola push, and you should handle it here
}


@Override
public void onNewToken(@NonNull String token) {
 super.onNewToken(token);
 TBLPushManager.onNewFirebaseToken(token);
}

Optional customization

TBLPushManager has a set for methods to customize notifications:

  • setNotificationIcon(int iconId) - Sets an icon to be displayed as an application icon in the notification UI. If not set, the application's icon is in use
  • setApplicationAppNameLabel(String applicationName) - Sets an application name to be displayed in the notification UI. If not set in code, the actual app name will be used. (Note that using this function overrides the application name from the SDK remote config file, controlled by Taboola)

Handling clicks

Clicks are handled by one method and action, for both Scheduled Notifications and Breaking News (Push notifications).

  1. Please add the following intent filter in your app manifest, within the activity that will handle clicks.
<!-- Handle Taboola Notification click -->
    <intent-filter>
        <action android:name="com.taboola.android.plus.notification.NOTIFICATION_CLICK_EVENT" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
  1. Handling the click in the Activity
    Tapping a notification will fire the com.taboola.android.plus.notification.NOTIFICATION_CLICK_EVENT intent, with all the relevant data added as extras on the Intent object.

TBLNotificationManager.handleClick() method must be called after clicking on the notification, and as a result, a ChromeCusotmTab tab will be opened.

@Override
protected void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 if (savedInstanceState == null) { // avoid handling click again when activity is recreated
   TBLNotificationManager.handleClick(intent, this);
 }
}

@Override
protected void onNewIntent(Intent intent) {
   super.onNewIntent(intent);
  TBLNotificationManager.handleClick(intent, this);
}

Restart App on phone reboot

To be able to launch the app on phone boot completed, we recommend you implement these 3 simple steps.

  1. Add permission to the app manifest
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
  1. Create a broadcast receiver that will start the app when the message is received
public class PhoneBootedReceiver extends BroadcastReceiver {
 @Override
 public void onReceive(Context context, Intent intent) {
  startApp();
 }

 private void startApp() {
  //launch you app
 }
}

Register broadcast receiver in the manifest file with filter to listen to the phone reboot

<receiver android:name=".PhoneBootedReceiver">
  <intent-filter>
    <action android:name="android.intent.action.BOOT_COMPLETED" />
  </intent-filter>
</receiver>

Example app

Use the following github repository for an example Android app which uses the SDK+

https://github.com/taboola/taboola-android-plus

ProGuard

SDK Plus 2.0 is using automated consumed Proguard rules. There is no need to add any rules manually.

License

This program is licensed under the Taboola, Inc. SDK License Agreement (the “License Agreement”). By copying, using or redistributing this program, you agree with the terms of the License Agreement. The full text of the license agreement can be found at https://sdk.taboola.com/taboolasdk/docs/taboola-android-sdk-license. Copyright 2020 Taboola, Inc. All rights reserved.

Changelog

[2.5.0] - 2022-03-08

  • Migrate from JobSchedular to WorkManager

[2.4.0] - 2021-11-15

  • Improved Scheduled Notification flow.

[2.2.2] - 2021-11-01

  • Support for Android 12

[2.2.2] - 2021-10-06

  • Migrate to androidX
  • Improve push notifications flow.
  • Update to latest firebase version

[2.2.0] - 2021-05-21

  • Bug fixes

[2.0.0] - 2020-05-18

Official release of SDK+ 2.0.0

[2.0.0-rc3] - 2020-05-02

Fixed:

  • More stability fixes

[2.0.0-rc1] - 2020-04-16

Added:

  • Complete refactoring of the SDK! SDK Plus now officially support sending both Push Notifications (breaking news), and scheduled notifications
  • New notifications UI modes when displaying sponsored items with a clear "Sponsored" label

Improved:

  • Removed the Home screen News feature

[1.4.0] - 20120-03-03

Added:

  • Added an option to manually render the notification - this feature is closed and requires special approval from Taboola
  • Together with the manual rendering, we added events the publisher requires to send when using the SDK Plus manually (not recommended, and requires special approval from Taboola)

Improved:

  • SDK Plus is now using Picasso 2.71828 dependency

[1.3.5] - 2020-02-12:

Fixed:

  • Fixed several crashes related to OOM

[1.3.4] - 2020-01-01:

Added:

  • Added support for push notifications - please contact your account manager for more information

Improved:

  • BI reporting
  • Performance
  • Monitoring

Fixed:

  • Broken config crashes
  • Upgrade versions bug
  • Blinking screen after custom unlock on Samsung devices

[1.2.2] - 2019-10-07:

Added:

  • Localization & data validation for push notifications

Improved:

  • BI reporting
  • Config properties
  • Click URL handling

Fixed:

  • format for “time” field in events that are sent to TRC
  • checking WI-FI availability
  • “Read more” invalid thumbnail

[1.1.0] - 2019-07-17

Added:

  • Server response validation
  • Analytics improvements

Fixed:

  • Internal bugs

Updated 3 months ago