Taboola iOS Push Implementation Guide

Integrate the Taboola Push SDK into your iOS 14 or later app, including notification tracking, service extensions, App Groups, foreground handling, delivery controls, and logging.

See the example app for a working implementation.

Prerequisites

Before you integrate the SDK:

1. Set your app's deployment target to iOS 14 or later.
2. Send your Taboola contact your app bundle ID so Taboola can identify your app.
3. Send your Taboola contact push-notification credentials:
   • A .p8 file (recommended), its Key ID, and its Team ID.
   • Or, a .p12 file and the password protecting it. A .p12 certificate expires after one year.
4. Obtain your publisher name from Taboola. You use it to initialize the SDK.

Set up the SDK

1. Add the dependency

Add TaboolaPush with CocoaPods or Swift Package Manager.

pod 'TaboolaPush', '1.0.0'

https://github.com/taboola/taboola-spm-ios-push-sdk

2. Initialize the SDK

Initialize the SDK early in your app startup. Set the notification center delegate to receive notification callbacks, then request notification permission.

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    UNUserNotificationCenter.current().delegate = self

    let builder = TaboolaPushSDKBuilder(
        publisherName: "your-publisher-name",
        appGroupId: "app-group-id"
    )
    .push()
    .build()

    TaboolaPushSDK.initialize(config: builder)
    TaboolaPushSDK.askForNotificationsPermission()

    return true
}

Optional: Initialize with a legacy API key

Direct API-key initialization is deprecated as of version 1.0.0. Use it only for an existing integration that still requires it.

let builder = TaboolaPushSDKBuilder(
    apiKey: "api_key",
    appGroupId: "app-group-id"
)
.push()
.build()

TaboolaPushSDK.initialize(config: builder)

To show the notification-permission prompt later, call:

TaboolaPushSDK.askForNotificationsPermission()

3. Register the device token

Forward the device token that iOS returns to the Taboola Push SDK.

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    TaboolaPushSDK.register(deviceToken)
}

4. Track notification opens

When a user taps a push notification, pass the UNNotificationResponse to pushTrackOpen. This reports the push open to Taboola.

Choose whether Taboola opens the click URL or your app handles it.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    TaboolaPushSDK.pushTrackOpen(
        handleUrl: true,
        response: response,
        completion: { url in
            // Continue after the SDK handles the notification URL.
        }
    )

    completionHandler()
}

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    TaboolaPushSDK.pushTrackOpen(
        handleUrl: false,
        response: response,
        completion: { url in
            // Navigate using the click URL and your app-specific routing.
        }
    )

    completionHandler()
}

You can call pushTrackOpen after additional app logic, but you must pass the UNNotificationResponse from the notification callback.

5. Enable required capabilities

1. Select the main application target in Xcode.
2. Open Signing & Capabilities, select + Capability, and enable Push Notifications.
3. Add the Background Modes capability.
4. Under Background Modes, enable Background processing and Remote notifications.

Optional: Configure the background mode in Info.plist

Open Info.plist as source code and add remote-notification to UIBackgroundModes.

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

6. Receive SDK initialization callbacks

Conform to TaboolaPushSDKDelegate, assign self to TaboolaPushSDK.taboolaDelegate, and implement taboolaPushSDKInited(_:) where you need to react to SDK initialization.

class MyClass: UIViewController, TaboolaPushSDKDelegate {
    func configureTaboolaPushDelegate() {
        TaboolaPushSDK.taboolaDelegate = self
    }

    func taboolaPushSDKInited(_ success: Bool) {
        // Run logic that depends on SDK initialization here.
    }
}

7. Add a Notification Service Extension

1. In Xcode, select File → New → Target.
2. Select Notification Service Extension.
3. Enter TaboolaSDKNotificationServiceExtension as the product name, then select Finish.
4. Select Cancel when Xcode asks to activate the new scheme. This keeps debugging focused on your main app; switch schemes next to the Run button when needed.
5. In the project navigator, select the top-level project, then select the TaboolaSDKNotificationServiceExtension target.
6. On the General tab, set the deployment target to iOS 14.
7. Open NotificationViewController.swift and replace its contents with the following code:

import UserNotifications
import UIKit
import TaboolaPush

class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?
    var receivedRequest: UNNotificationRequest!

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        TaboolaPushSDK.setValueFor("app-group-id")

        self.contentHandler = contentHandler
        receivedRequest = request
        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent

        if let bestAttemptContent = bestAttemptContent {
            TaboolaPushSDK.didReceiveNotification(
                with: request,
                best: bestAttemptContent
            ) { bestAttempt in
                contentHandler(bestAttempt)
            }
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.  
        // Use this as an opportunity to deliver your "best attempt" at modified content, 	otherwise the original push payload will be used.  

        if let contentHandler = contentHandler,
           let bestAttemptContent = bestAttemptContent {
            TaboolaPushSDK.notificationBuilderWillTerminate(
                with: receivedRequest.content.userInfo,
                best: bestAttemptContent
            ) { best in
                contentHandler(best)
            }
        }
    }
}

8. Enable the App Groups capability

Enable App Groups for your main app target and TaboolaSDKNotificationServiceExtension. If you added a content extension and want to activate it there, enable App Groups for that target as well.

1. Open Signing & Capabilities for each applicable target.
2. Select + Capability, then add App Groups.
3. Select an existing App Group or create one with +.
4. Select the same App Group name for every applicable target.
5. Pass the App Group name when you initialize TaboolaPushSDKBuilder:

let builder = TaboolaPushSDKBuilder(
    publisherName: "your-publisher-name",
    appGroupId: "app-group-id"
)
.push()
.build()

Set the App Group name in every extension that uses TaboolaPushSDK. The service-extension example in the previous step includes this call:

TaboolaPushSDK.setValueFor("app-group-id")

9. Handle notifications while your app is in the foreground

Add the following UNUserNotificationCenterDelegate method to your AppDelegate class to present notifications while the app is in the foreground.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
    completionHandler([.alert, .sound, .badge, .list])
}

10. Use additional methods

Control notification delivery

Call setNotificationsDelivery(active:) to programmatically control notification delivery for a device. The method tracks the delivery-status change and sends the updated preference to the server.

Use it to provide an in-app control that pauses or resumes push notifications without revoking system-level permissions.

TaboolaPushSDK.setNotificationsDelivery(active: Bool)

Get the notification destination URL

Call getCleanUrl() to retrieve the cleaned and decoded destination URL embedded in a push notification.

TaboolaPushSDK.getCleanUrl() -> String

11. Configure logging

Call setLogLevel before SDK initialization to control console-output verbosity.

For example, show only errors in production:

TaboolaPushSDK.setLogLevel(.error)