AndroidiOSAnnouncementsSupport Forum
SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum
SDK Documentation

Stories

iOS Classic - Stories

Suggest Edits

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

  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).
  3. Get the TBLStoriesCollectionView from the Stories Unit.

In your UIViewController, perform the following steps:

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

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

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

  1. Add the TBLStoriesCollectionView as a sub-view of the UIView.

  2. 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
    }
 }
  1. 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:

ValueExplanation
STORIES_VIEW_FAILED_LOADINGThe main Stories view failed to load.
FULL_SCREEN_FAILED_LOADINGThe full-screen view for the selected topic failed to load.
CLASSIC_UNIT_ERRORA 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.

Updated about 1 month ago