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

In your AppDelegate class, create a TBLPublisherInfo object and initialize Taboola:

#import <TaboolaSDK/TaboolaSDK.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Immediately after application launch...
  
    // Initialize a TBLPublisherInfo instance with your unique 'publisherName':
    TBLPublisherInfo *publisherInfo = [[TBLPublisherInfo alloc]initWithPublisherName:@"<publisherName>"];

    // Initialize Taboola for your application:
    [Taboola initWithPublisherInfo:publisherInfo];
  
    // (Optional) Set *global* feature flags:
    [Taboola setGlobalExtraProperties:@{@"<feature flag key>":@"<value>"}];

    // (Optional) Set the desired log level: 
    [Taboola setLogLevel:LogLevelDebug];
    
    return YES;
}

import TaboolaSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Immediately after application launch...
  
    // Initialize a TBLPublisherInfo instance with your unique 'publisherName' (aka 'Publisher ID'):
    let publisherInfo = TBLPublisherInfo.init(publisherName: "<publisherName>")
    
    // Initialize Taboola for your application:
    Taboola.initWith(publisherInfo)
    
    // (Optional) Set *global* feature flags:
    Taboola.setGlobalExtraProperties(["<feature flag key>":"<value>"])
   
    // (Optional) Set the desired log level:
    Taboola.setLogLevel(LogLevel.debug)
    
    return true
}

📘
publisherName
publisherName (aka Publisher ID) is a unique, alphabetic String. It might contain dashes - e.g. "{user.publisherID}" - but not spaces.
To obtain your Publisher ID, contact your Taboola Account Manager.

🚧
AppDelegate
Initialize Taboola in your AppDelegate class - or as early as possible within the app.

📘
Logging
(Optional) To set the desired log level, use the setLogLevel method.
For more detail, see: Setters.

Build Taboola content instances

🚧
Overview

For each screen, obtain a TBLClassicPage instance.

Use the Page instance to build a Stories Unit (and any other desired Units - see: Basic Integration).

Get the TBLStoriesCollectionView from the Stories Unit.

In your UIViewController, perform the following steps:

Initialize a TBLClassicPage instance:

#import <TaboolaSDK/TaboolaSDK.h>
  
// In your ViewController:
  
@property (nonatomic, strong) TBLClassicPage *classicPage;

- (void)viewDidLoad {
    
    // Step 1 (this step):
    _classicPage = 
    [[TBLClassicPage alloc]initWithPageType:<pageType> pageUrl:<pageUrl> delegate:self scrollView:<yourScrollView>];

}

import TaboolaSDK

// In your ViewController:

var classicPage: TBLClassicPage?

override func viewDidLoad() {

    // Step 1 (this step):
    classicPage = 
    TBLClassicPage.init(pageType: <pageType>, pageUrl: <pageUrl>, delegate: self, scrollView: <yourScrollView>)
  
}

📘
Params

pageType - The page type, as provided by Taboola - e.g. "article".

pageUrl - A fully-qualified, public URL, with the same content as this screen:

e.g. "https://www.example.com/articles?id=123"

delegate - A class instance that implements the TBLClassicPageDelegate protocol - e.g. self (See: Events)

scrollView - The scroll view in which you will embed the Taboola content instance(s).

e.g. _collectionView, _tableView, _scrollView (Objective C)

e.g. self.collectionView, self.tableView, self.scrollView (Swift)

🚧
Guidelines

Each ViewController must have its own instance of TBLClassicPage.

To maintain a smooth user experience, create the Stories Unit as soon as the view has loaded - i.e. in the viewDidLoad method.

Build a TBLStoriesUnit instance, for that Page:

#import <TaboolaSDK/TaboolaSDK.h>
  
// In your ViewController:
  
@property (nonatomic, strong) TBLClassicPage *classicPage;
@property (nonatomic, strong) TBLStoriesUnit *storiesUnit;

- (void)viewDidLoad {

    // Step 1:
    _classicPage = [[TBLClassicPage alloc]initWithPageType:<pageType> pageUrl:<pageUrl> delegate:self scrollView:<yourScrollView>];
    
    // Step 2 (this step):
    _storiesUnit = [classicPage createStoryUnitWithPlacementName:<placement> mode:<mode> extraParameters:<extraParams> delegate:self];
}

import TaboolaSDK

// In your ViewController:

var classicPage: TBLClassicPage?
var storiesUnit: TBLStoriesUnit?

override func viewDidLoad() {
  
    // Step 1:
    classicPage = TBLClassicPage.init(pageType: <pageType>, pageUrl: <pageUrl>, delegate: self, scrollView: <yourScrollView>)
    
    // Step 2 (this step):
    storiesUnit = classicPage?.createStoryUnit(withPlacementName: <placement>, mode: <mode>, extraParameters: <extraParams>, delegate: self)

}

📘
Params

placementName - The placement name, as provided by Taboola - e.g. "stories-prod".

mode - The UI Mode ID of the placement, as provided by Taboola - e.g. "thumbnails-feed".

extraParameters - An NSDictionary containing extra configuration parameters, as provided by your Taboola Account Manager. If not relevant, pass an empty dictionary, e.g.:

extraParameters:@{} (Objective C)

extraParameters:[:] (Swift)

delegate - A class instance that implements the TBLStoriesUnitDelegate protocol - e.g. self.

Get the TBLStoriesCollectionView from the Stories Unit:

#import <TaboolaSDK/TaboolaSDK.h>
  
// In your ViewController:
  
@property (nonatomic, strong) TBLClassicPage *classicPage;
@property (nonatomic, strong) TBLStoriesUnit *storiesUnit;
@property (nonatomic, strong) TBLStoriesCollectionView *storiesCollectionView;

- (void)viewDidLoad {

    // Step 1:
    _classicPage = [[TBLClassicPage alloc]initWithPageType:<pageType> pageUrl:<pageUrl> delegate:self scrollView:<yourScrollView>];
    
    // Step 2:
    _storiesUnit = [classicPage createStoryUnitWithPlacementName:<placement> mode:<mode> extraParameters:<extraParams> delegate:self];
  
    // Step 3 (this step):
    _storiesCollectionView = storiesUnit.storiesCollectionView;
    
}

import TaboolaSDK

// In your ViewController:

var classicPage: TBLClassicPage?
var storiesUnit: TBLStoriesUnit?
var storiesCollectionView: TBLStoriesCollectionView?

override func viewDidLoad() {
  
    // Step 1:
    classicPage = TBLClassicPage.init(pageType: <pageType>, pageUrl: <pageUrl>, delegate: self, scrollView: <yourScrollView>)
    
    // Step 2:
    storiesUnit = classicPage?.createStoryUnit(withPlacementName: <placement>, mode: <mode>, extraParameters: <extraParams>, delegate: self)

    // Step 3 (this step):
    storiesCollectionView = storiesUnit.storiesCollectionView
}

📘
TBLStoriesCollectionView inherits from UICollectionView.

Fetch Taboola content:

#import <TaboolaSDK/TaboolaSDK.h>
  
// In your ViewController:
  
@property (nonatomic, strong) TBLClassicPage *classicPage;
@property (nonatomic, strong) TBLStoriesUnit *storiesUnit;
@property (nonatomic, strong) TBLStoriesCollectionView *storiesCollectionView;

- (void)viewDidLoad {

    // Step 1:
    _classicPage = [[TBLClassicPage alloc]initWithPageType:<pageType> pageUrl:<pageUrl> delegate:self scrollView:<yourScrollView>];
    
    // Step 2:
    _storiesUnit = [classicPage createStoryUnitWithPlacementName:<placement> mode:<mode> extraParameters:<extraParams> delegate:self];
  
    // Step 3:
    _storiesCollectionView = storiesUnit.storiesCollectionView;
  
    // Step 4 (this step):
    [_storiesUnit fetchContent];
    
}

import TaboolaSDK

// In your ViewController:

var classicPage: TBLClassicPage?
var storiesUnit: TBLStoriesUnit?
var storiesCollectionView: TBLStoriesCollectionView?

override func viewDidLoad() {
  
    // Step 1:
    classicPage = TBLClassicPage.init(pageType: <pageType>, pageUrl: <pageUrl>, delegate: self, scrollView: <yourScrollView>)
    
    // Step 2:
    storiesUnit = classicPage?.createStoryUnit(withPlacementName: <placement>, mode: <mode>, extraParameters: <extraParams>, delegate: self)

    // Step 3:
    storiesCollectionView = storiesUnit.storiesCollectionView
  
    // Step 4 (this step):
    storiesUnit.fetchContent()
}

Manage the layout

Create a UIView to contain the TBLStoriesCollectionView:

@property (weak, nonatomic) IBOutlet UIView *storiesContainerView;

@IBOutlet weak var storiesContainerView: UIView!

📘
You can create the UIView via the Storyboard or via code.

Add the TBLStoriesCollectionView as a sub-view of the UIView.
Constrain the TBLStoriesCollectionView layout to the UIView - for example:

-(void)setConstraints {    
   [_storiesContainerView addSubview:_storiesCollectionView];     
   _storiesCollectionView.translatesAutoresizingMaskIntoConstraints = NO;     
   [_storiesCollectionView.topAnchor constraintEqualToAnchor: _storiesContainerView.topAnchor constant:0].active = YES; 
   [_storiesCollectionView.bottomAnchor constraintEqualToAnchor: _storiesContainerView.bottomAnchor constant:0].active = YES; 
   [_storiesCollectionView.leadingAnchor constraintEqualToAnchor: _storiesContainerView.leadingAnchor constant:0].active = YES;
   [_storiesCollectionView.trailingAnchor constraintEqualToAnchor: _storiesContainerView.trailingAnchor constant:0].active = YES;
}

func setTaboolaConstraintsToSuper() {
    if let storiesCollectionView = storiesCollectionView {
        storiesContainerView.addSubview(storiesCollectionView)
        storiesCollectionView.translatesAutoresizingMaskIntoConstraints = false
        storiesCollectionView.topAnchor.constraint(equalTo: storiesContainerView.topAnchor, constant: 0).active = true
        storiesCollectionView.bottomAnchor.constraint(equalTo: storiesContainerView.bottomAnchor, constant: 0).active = true
        storiesCollectionView.leadingAnchor.constraint(equalTo: storiesContainerView.leadingAnchor, constant: 0).active = true
        storiesCollectionView.trailingAnchor.constraint(equalTo: storiesContainerView.trailingAnchor, constant: 0).active = true
    }
 }

That's it! Taboola SDK will handle the rest. 🙂

📘
Unlike TBLClassicUnit, TBLStoriesUnit does not provide a fetchContent() method.

Event Handling

When fetching and displaying Stories, you may need to handle certain events. Taboola SDK provides a TBLStoriesUnitDelegate for event handling.

📘
All methods in TBLStoriesUnitDelegate are optional - you can implement those of interest and ignore the rest.

Available Events

storiesViewDidLoad

Stories view has loaded, and the carousel has displayed:

- (void)storiesViewDidLoad;

func storiesViewDidLoad()

storiesFullScreenDidOpen

Full-screen view for the selected topic has opened:

- (void)storiesFullScreenDidOpen;

func storiesFullScreenDidOpen()

storiesFullScreenDidClose

Full-screen view for the selected topic has closed:

- (void)storiesFullScreenDidClose;

func storiesFullScreenDidClose()

storiesDidFailWithError

An error was thrown by the Stories Unit

- (void)storiesDidFailWithError:(NSString *)error;

func storiesDidFailWithError(_ error: String)

Possible values for error:

Value	Explanation
`STORIES_VIEW_FAILED_LOADING`	The main Stories view failed to load.
`FULL_SCREEN_FAILED_LOADING`	The full-screen view for the selected topic failed to load.
`CLASSIC_UNIT_ERROR`	A general error occurred with the Taboola Unit.

Sample code snippet:

- (void)storiesDidFailWithError:(NSString *)error {
    // Collapse and hide Taboola content:
    [_storiesContainerView.heightAnchor constraintEqualToConstant:0].active = YES;
}

func storiesDidFailWithError(_ error: String) {
  storiesContainerView.heightAnchor.constraint(equalToConstant: 0).active = true
}

Swipe Up

Within the full screen view (of a selected topic), the user can swipe up to read more. The swipe up action triggers the didClickPlacementName event in TBLClassicPageDelegate.

For more information about TBLClassicPageDelegate, see: iOS - Classic > Event Handling

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.

Stories

Overview

Initialize Taboola

publisherName

AppDelegate

Logging

Build Taboola content instances

Overview

Params

Guidelines

Params

`TBLStoriesCollectionView` inherits from `UICollectionView`.

Manage the layout

You can create the `UIView` via the Storyboard or via code.

Unlike `TBLClassicUnit`, `TBLStoriesUnit` does not provide a `fetchContent()` method.

Event Handling

All methods in `TBLStoriesUnitDelegate` are optional - you can implement those of interest and ignore the rest.

Available Events

storiesViewDidLoad

storiesFullScreenDidOpen

storiesFullScreenDidClose

storiesDidFailWithError

Swipe Up

Well Done!

Well Done

Taboola content not rendering?

What's next?

Overview

Initialize Taboola

publisherName

AppDelegate

Logging

Build Taboola content instances

Overview

Params

Guidelines

Params

TBLStoriesCollectionView inherits from UICollectionView.

Manage the layout

You can create the UIView via the Storyboard or via code.

Unlike TBLClassicUnit, TBLStoriesUnit does not provide a fetchContent() method.

Event Handling

All methods in TBLStoriesUnitDelegate are optional - you can implement those of interest and ignore the rest.

Available Events

storiesViewDidLoad

storiesFullScreenDidOpen

storiesFullScreenDidClose

storiesDidFailWithError

Swipe Up

Well Done!

Well Done

Taboola content not rendering?

What's next?

`TBLStoriesCollectionView` inherits from `UICollectionView`.

You can create the `UIView` via the Storyboard or via code.

Unlike `TBLClassicUnit`, `TBLStoriesUnit` does not provide a `fetchContent()` method.

All methods in `TBLStoriesUnitDelegate` are optional - you can implement those of interest and ignore the rest.