Stories

Overview

With Classic Integration, you can display content as Stories - much the same as the Stories format used on social media.

The flow is similar to a regular Widget or Feed (see: Basic Integration).

📘

You can also combine different display formats - e.g. embed a Stories Unit, Widget Unit and/or Feed Unit on the same page. (See: Basic Integration)

Initialize Taboola

🚧

Initialization is required once per application. It should be done as early as possible - preferably in a sub-class of Application.

1. Create a TBLPublisherInfo object and initialize Taboola:

TBLPublisherInfo publisherInfo = new TBLPublisherInfo("publisher-id");
Taboola.init(publisherInfo);

📘

Your Publisher ID (aka Publisher Name) is a unique, alphabetic string. It might contain dashes - e.g. "<<publisherID>>" - but not spaces.

Build Taboola content instances

Flow 1: Via code (recommended)

🚧

Overview

1. For each screen, obtain a TBLClassicPage instance.
2. Use the Page instance to build a Stories Unit (and any other desired Units - see: Basic Integration).
   1. Make sure to use a unique placement name for each Unit on the page.
3. Add the Stories Unit (and any other desired Units) to the layout via code.

🚧

Guidelines

1. Do not invoke the addStoriesUnitToPage() method - the Stories Unit instance returned already belongs to that Page instance.
2. (Similarly, do not invoke the addUnitToPage() method for any other Unit instances that you defined.)

In your Activity/Fragment Java file:

1. Obtain a TBLClassicPage instance for that screen, passing the relevant pageUrl and pageType (e.g. "<<pageType>>"):

TBLClassicPage classicPage = 
Taboola.getClassicPage(<pageUrl>, <pageType>);

📘

For an explanation of each param, see: Params.

2. Build a TBLStoriesUnit instance, for that Page:

TBLStoriesUnit storiesUnit = 
classicPage.buildStoriesUnit(<Context>, <placementName>, <mode>, <placementType>, new TBLStoriesListener() {});

📘

For an explanation of each param, see: Params.

📘

• Pass a TBLStoriesListener instance for event handling.
• For more information, see Event Handling (below).

3. Add the TBLStoriesUnit instance to your layout:

// Use similar code for your specific layout:
FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(storiesUnit);

Flow 2: Via XML

🚧

Overview

1. For each screen, obtain a TBLClassicPage instance in your Activity/Fragment Java file.
2. In the corresponding layout file, add a TBLStoriesUnit XML element.
   1. (If relevant, you can add TBLClassicUnit XML elements to the same layout file - see: Basic Integration.)
   2. (Make sure to assign a unique placement name to each XML element.)
3. In your Activity/Fragment Java file, use the addStoriesUnitToPage() method to attach the TBLStoriesUnit instance to your TBLClassicPage instance.
4. (If relevant, use the addUnitToPage() method to do the same for your TBLClassicUnit XML elements - see: Basic Integration.)

🚧

Guidelines

1. Invoke the addStoriesUnitToPage() method for the TBLStoriesUnit XML element that you defined.
2. (If relevant, invoke the addUnitToPage() method for any TBLClassicUnit XML elements that you defined.)

In your Activity/Fragment Java file:

1. Obtain a TBLClassicPage instance for that screen, passing the relevant pageUrl and pageType (e.g. "<<pageType>>"):

TBLClassicPage classicPage = 
Taboola.getClassicPage(<pageUrl>, <pageType>);

📘

For an explanation of each param, see: Params.

In the corresponding layout file:

2. Add a com.taboola.android.TBLStoriesUnit element:

<com.taboola.android.TBLStoriesUnit
    android:id="@+id/stories_unit"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
/>

🚧

The Unit will resize itself when it loads. Make sure to set the height to "wrap_content".

In your Activity/Fragment Java file:

4. Add the Unit to the relevant Page instance, by invoking the addStoriesUnitToPage() method.

TBLStoriesUnit storiesUnit = view.findViewById(R.id.taboola_view);

// Invoke the 'addStoriesUnitToPage()' method for Story Units that were built via XML:
classicPage.addStoriesUnitToPage(storiesUnit, <placementName>, <mode>, <placementType>, new TBLStoriesListener() {});

📘

For an explanation of each param, see: Params.

📘

For information about the TBLStoriesListener abstract class and event handing, see Event Handling (below).

Show Taboola Content

1. Fetch content for the Stories Unit:

storiesUnit.fetchContent();

🚧

Make sure to add the Stories Unit to your layout and fetch content as soon as the screen loads.

Ideally, this should be done in onCreate() for an Activity - or in onCreateView() for a Fragment.

Event Handling

When using Taboola Stories, you may want to handle certain events. The supported events are described below.

TBLStoriesListener

TBLStoriesListener extends TBLClassicListener. You can use it to register for any of the TBLClassicListener events, as well as events that are specific to Stories.

📘

For more information about TBLClassicListener events, see: Android - Classic > Event Handling

TBLStoriesListener supports the following events for Stories.

You can optionally override any events (methods) of interest:

public abstract class TBLStoriesListener extends TBLClassicListener {

    /**
     * Stories view has loaded, and the carousel has displayed:
     */
    public void onStoriesViewLoaded() {
    }

    /**
     * An error was thrown by the Stories Unit:
     */
    public void onStoriesError(String error) {
    }

    /**
     * Full-screen view for the selected topic has opened:
     */
    public void onStoriesFullScreenOpen() {

    }

    /**
     * Full-screen view for the selected topic has closed:
     */
    public void onStoriesFullScreenClose() {
    }
}

📘

TBLStoriesListener is an abstract class. You can override events (methods) of interest and ignore the rest.

Possible values for error:

A sample code snippet for event handling:

TBLStoriesUnit storiesUnit = 
classicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLStoriesListener() {
    
    // Override any methods of interest. Some examples follow...
  
    // 'onItemClick' (inherited from TBLClassicListener):    
    @Override
    public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, String customData) {
        Log.d(TAG,"onItemClick " + itemId);
        return super.onItemClick(placementName, itemId, clickUrl, isOrganic, customData);
    }
    
    // `onStoriesError`:
    @Override
    public void onStoriesError(String error) {
        Log.d(TAG, error);
        if (error.equals(StoriesErrors.STORIES_VIEW_FAILED_LOADING)) {
          // Adjust the UI - e.g. collapse and hide Taboola content...
        }
    }  
    
});

Screen Orientation

During the fullscreen UX for Stories, Taboola SDK locks the screen orientation in portrait mode. You can override this default behavior via the setOrientationLock method:

storiesUnit.setOrientationLock(false) // default is `true`

Well Done!

🙂

Well Done

You have completed the Stories integration steps!
If everything is working smoothly, take a look at the What's Next section below.

🙈

Taboola content not rendering?

Submit a question on our forum.

What's next?

Want to embed a classic Taboola Widget or Feed? See: Basic Integration.

In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR & CCPA respectively.

Once you are complete, submit your app for review - see the App Verification section.