AndroidiOSAnnouncementsSupport Forum
SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum
SDK Documentation

Advanced Options

iOS Classic - Advanced Options

Suggest Edits

Multiple units on 1 page

If a given screen/page contains multiple Units, Taboola loads each Unit loads sequentially, with a preset timeout value. This allows Taboola to prevent duplicate content.

You can customize this behavior at the Page level - as described below.

Custom timeout for serial loading

During serial loading, Taboola SDK loads each Unit sequentially: as soon as a given Unit has loaded, the next one starts loading.

A default timeout of 10,000 ms is applied. If a given Unit has not loaded within that time, Taboola SDK will move onto the next one.

To adjust this timeout value, invoke the setSerialFetchTimeout method at the Page level.

📘

Applies to serial loading (FetchingPolicySerial) only.

After initializing TBLClassicPage:

_classicPage.serialDelay = 2000;

classicPage?.serialDelay = 2000

Parallel loading

By default, Taboola SDK uses serial loading (FetchingPolicySerial). To adjust this default behavior, set the fetchingPolicy property.

🚧

When loading Units in parallel, Taboola cannot guarantee unique content across Units.

After initializing TBLClassicPage:

_classicPage.fetchingPolicy = FetchingPolicyParallel;

classicPage?.fetchingPolicy = FetchingPolicy.parallel

📘

Possible values:

  • FetchingPolicySerial - serial loading of Units (default).
  • FetchingPolicyParallel - parallel loading of Units.

Progress Bar

When the user scrolls down in your app and encounters a Taboola Feed, the SDK automatically switches the scroll from your app to the Feed (i.e. to the Feed's web view).

Each time this occurs, a progress bar displays.

📘

The progress bar ensures a better UX.

It applies for both automatic scroll switch (default) and manual scroll switch (see below).

🚧

The progress bar applies to Feed only.

You can control the progress bar visibility and color, using the following functions.

After building the TBLClassicUnit instance, set the desired progress bar properties:

// Sets the *color* of the progress bar. (Default is dark blue.)
_feedUnit.progressBarColor = @"#4286f4";

// Sets the progress bar *duration*, in seconds. (Default is 0.7 seconds.)
_feedUnit.progressBarDuration = 1;

// Activate/deactivate the progress bar.
// Default value is 'Yes'.
_feedUnit.progressBarEnabled = Yes;

// Shows the progress bar at the bottom of the screen. 
// Applies to: *manual scroll switch* (see below).
[_feedUnit startProgressBarAnimation];

// Sets the *color* of the progress bar. (Default is dark blue.)
feedUnit.progressBarColor = "#4286f4"

// Sets the progress bar *duration*, in seconds. (Default is 0.7 seconds.)
feedUnit.progressBarDuration = 1

// Activate/deactivate the progress bar.
// Default value is 'Yes'.
feedUnit.progressBarEnabled = true

// Shows the progress bar at the bottom of the screen. 
// Applies to: *manual scroll switch* (see below).
feedUnit.startProgressBarAnimation()

Manual Scroll Switch

When the user scrolls down in your app and encounters a Taboola Feed, the SDK automatically switches the scroll from your app to the Feed (i.e. to the Feed's web view). By default, this scroll switch is handled automatically by Taboola SDK, without any action on your part.

You can override this default behavior and implement the scroll switch yourself.

🚧

Manual scroll switch applies to Feed only.

In your ViewController class:

  1. After building the TBLClassicUnit instance, set the overrideScrollIntercept property:
_feedUnit.overrideScrollIntercept = YES;

feedUnit?.overrideScrollIntercept = true
  1. Update the following 2 delegate methods, to implement the scroll switch.

Taboola delegate (TBLClassicPageDelegate):

- (void)scrollViewDidScrollToTopClassicUnit:(UIView *)classicUnit {
  if (unit.scrollEnable) {
    NSLog(@"did finish scrolling taboola");
    if (self.obj.toastIsOn) {
      [_toastMessage showToastWithMessage:@"did finish scrolling taboola" fromViewController:self];
    }
    [unit setScrollEnable:NO];
    scrollView.scrollEnabled = YES;
    [unit startProgressBarAnimation];
  }
}

ScrollView delegate (UIScrollViewDelegate):

- (void)scrollViewDidScroll:(UIScrollView *)scrollView{
  if (_taboolaFeed.overrideScrollIntercept == YES) {
    [self didEndScrollOfParentScroll:self.collectionView withTBLUnit:self.taboolaFeed];
  }
}

- (void)didEndScrollOfParentScroll:(UIScrollView *)scrollView withTBLUnit:(TBLClassicUnit *)unit {
  float height = scrollView.frame.size.height;
  float contentYoffset = scrollView.contentOffset.y;
  if (@available(iOS 11.0, *)) {
    contentYoffset = contentYoffset - scrollView.adjustedContentInset.bottom;
  }
  else {
    contentYoffset = contentYoffset - scrollView.contentInset.bottom;
  }
  float distanceFromBottom = scrollView.contentSize.height - contentYoffset;
  if ([unit superview] != nil &&
    distanceFromBottom < height &&
    scrollView.scrollEnabled &&
    scrollView.contentSize.height > 0 &&
    unit.frame.size.height >= [self getDoubleScreenHeight]) {
    scrollView.scrollEnabled = NO;
    NSLog(@"did finish parent scrolling");
    if (self.obj.toastIsOn) {
      [_toastMessage showToastWithMessage:@"did finish parent scrolling" fromViewController:self];
    }
    [unit setScrollEnable:YES];
    [unit startProgressBarAnimation];
  }
}

Publisher manages the cell

As mentioned under Basic Integration > Manage the layout, we recommend using Taboola SDK to manage the cell.

If you prefer to manage the cell yourself, follow the steps in this section.

Cell management

The following code fragment illustrates the overall concept for managing the cell yourself:

// sizeForItemAtIndexPath
-(CGSize)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout sizeForItemAtIndexPath:(NSIndexPath *)indexPath {
    
    // Widget size...
    return CGSizeMake(self.view.frame.size.width, _widgetUnit.placementHeight);
    
    // Feed size...
    return CGSizeMake(self.view.frame.size.width, feedUnit.placementHeight);
  
}

// cellForItemAtIndexPath
- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {

        // Widget...
        UICollectionViewCell *cell = [collectionView dequeueReusableCellWithReuseIdentifier:@"TaboolaCollectionViewCell" forIndexPath:indexPath];
        
        // Remove Taboola from the cell
        for (UIView *view in [cell.contentView subviews]) {
            [view removeFromSuperview];
        }
        // Add Widget to the cell
        [cell.contentView addSubview:_widgetUnit];
        
        return cell;

        // Feed...
        UICollectionViewCell *cell = [collectionView dequeueReusableCellWithReuseIdentifier:@"TaboolaCollectionViewCell" forIndexPath:indexPath];

        // Remove Taboola from the cell
        for (UIView *view in [cell.contentView subviews]) {
            [view removeFromSuperview];
        }
        // Add Feed to the cell
        [cell.contentView addSubview:_feedUnit];
        
        return cell;
}

// sizeForItemAt
func collectionView(_ collectionView: UICollectionView, layout collectionViewLayout: UICollectionViewLayout, sizeForItemAt indexPath: IndexPath) -> CGSize {

    // Widget size...
    return CGSize(width: self.view.frame.size.width, height: widgetUnit?.placementHeight ?? 200)
    
    // Feed size...
    return CGSize(width: self.view.frame.size.width, height: feedUnit?.placementHeight ?? 200)

}
    
// cellForItemAt
func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
  
    // Widget cell
    let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "TaboolaCollectionViewCell", for: indexPath)

    if let widgetUnit = widgetUnit {
        // Remove Taboola from the cell
        for view in cell.subviews{
            view.removeFromSuperview()
        }
        // Add Widget to the cell        
        cell.addSubview(widgetUnit)
    }
    return cell

    // Feed cell
    let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "TaboolaCollectionViewCell", for: indexPath)

    if let feedUnit = feedUnit {
        // Remove Taboola from the cell
        for view in cell.subviews {
            view.removeFromSuperview()
        }
        // Add Feed to the cell        
        cell.addSubview(feedUnit)
    }
    return cell

}

When managing the cell yourself, you also need to handle the didLoadOrResizePlacement event - described next.

didLoadOrResizePlacement event

Returns the loaded placement with its updated height.

🚧

Only required when managing the cell yourself (see above).

We recommend using Taboola SDK to manage the cell. See: Basic Integration > Manage the layout.

-(void)taboolaView:(UIView *)taboolaView didLoadOrResizePlacement:(NSString *)placementName withHeight:(CGFloat)height placementType:(PlacementType)placementType{
    NSLog(@"%@", placementName);
    // If Taboola manages the UI (*recommended*), then NO special handling is required here.
    // Else - insert your code here:
    if ([placementName containsString:widgetPlacement]) {
        // Widget
        [_widgetUnit setFrame:CGRectMake(0, 0, self.view.frame.size.width, _widgetUnit.placementHeight)];
    } else {
        // Feed
        [_feedUnit setFrame:CGRectMake(__feedUnit.frame.origin.x, __feedUnit.frame.origin.y, self.view.frame.size.width, __feedUnit.placementHeight)];
    }
    [self.collectionView.collectionViewLayout invalidateLayout];
}

func taboolaView(_ taboolaView: UIView!, didLoadOrResizePlacement placementName: String!, withHeight height: CGFloat, placementType: PlacementType) {
        print("Placement name: \(String(describing: placementName)) has been loaded with height: \(height)")
        // If Taboola manages the UI (*recommended*), then NO special handling is required here.
        // Else - insert your code here:
        if placementName == Constants.widgetPlacement{
            // Widget
            widgetUnit?.frame = CGRect(x: 0,y: 0,width: self.view.frame.size.width,height: widgetUnit?.placementHeight ?? 200)
        }
        else {
            // Feed
            feedUnit?.frame = CGRect(x: feedUnit?.frame.origin.x ?? 0,y: feedUnit?.frame.origin.y ?? 0,width: self.view.frame.size.width,height: feedUnit?.placementHeight ?? 200)
        }
        self.collectionView.collectionViewLayout.invalidateLayout()
    }

📘

Params

  • placementName - The name of the placement loaded/resized.
  • height - The height, in pixels, of the placement loaded/resized.
  • placementType - Widget or Feed.

🚧

Insert resizing code for both Widget and Feed.

📘

For additional events, see: Event Handling.

Dark Mode

🚧

Configuring Dark Mode

Dark mode is not supported by default. For dark-mode placements, contact your Taboola Account Manager.

Once Taboola has configured your dark-mode placements, you can use the following code in your application:

[_classicPage setPageExtraProperties:@{@"darkMode":@"true"}];

classicPage?.pageExtraProperties = ["darkMode":"true"]

🚧

Swapping Between Dark & Light Themes

Setting extraProperties with "darkMode" "true" will send a request for "dark" content.
For light content do not set the extra Property and avoid using ["darkMode":"false"]

💁🏻

Need a hand?

Go ahead! Ask a question in our Support Forum.

Tip: Provide as much detail as possible, including your platform and SDK version.

Updated 2 months ago