SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum


## 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`:

ο»Ώ
  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

ο»Ώ

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

ο»Ώ

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](πŸ”—ο»Ώ)ο»Ώ

ο»Ώ

## 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

ο»Ώ

Example code with values:

ο»Ώ

## 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.

ο»Ώ

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

ο»Ώ

## 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.

ο»Ώ

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

ο»Ώ

## 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.

ο»Ώ
  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.

ο»Ώ

## 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

ο»Ώ
  1. Create a broadcast receiver that will start the app when the message is received

ο»Ώ

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

ο»Ώ

## 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