First Steps

📍

You are viewing the V3 docs. (For the V2 docs, go here.)

✅

While reading the documentation, take a look at our Sample App.

📘

The following steps are required for both Classic and Web integrations.

🚧

XCFramework bundle

As of SDK 3.8.20, Taboola SDK is built as an XCFramework bundle.

When using Carthage, make sure to reference the bundle accordingly - e.g. TaboolaSDK.xcframework.

Installation overview

1. Install the Taboola SDK, using any one of the following dependency managers:
   1. Swift Package Manager (SPM)
   2. CocoaPods
   3. Carthage
2. (Recommended) Add the SKAdNetwork ID for Taboola (requires Taboola SDK 3.2.0 or higher).

Flow 1: Install with SPM (Swift Package Manager)

1. Within Xcode, select the Help menu. Start typing "Add Packages...", and then select it from the options shown.
2. A modal dialogue displays:
   1. [UPDATED URL] In the search box (top, right), paste in this URL: https://github.com/taboola-automation/taboola-ios-sdk-spm
      https://github.com/taboola/taboola-spm-ios-sdk

      Information about the Taboola SDK package is shown.

   2. Tip: Using the dropdown provided (top), add a dependency rule - e.g. Up To Next Major Version.
   3. Click on ‘Add Package’ (bottom, right).

      The package tree displays in the Project navigator pane, under Package Dependencies.

Flow 2: Install with CocoaPods

Install CocoaPods on your system

If not already present, install CocoaPods on your system:

1. Run the following command from the Terminal:

$ sudo gem install cocoapods

2. Wait for the installation to complete. Then run the following command to complete the setup:

pod setup --verbose

📘

The above installation is required once per system.

Install Taboola SDK for your project

1. Using the Terminal, navigate to your iOS project directory and run the following command:

$ pod init

📘

This creates a Podfile for your project.

2. Using a text editor, open your Podfile. Add the Taboola SDK dependency, with an exact version number - and save:

target 'DemoProject' do
 
  # Comment out the next line if you're not using Swift and you don't want to use dynamic frameworks.
  use_frameworks!

  # Taboola SDK
  pod 'TaboolaSDK', '<<iosSDKVersion>>'

end

🚧

Make sure to indicate the latest version - e.g. <<iosSDKVersion>>.

3. Using the Terminal, navigate to your iOS project directory and install the Taboola SDK:

$ pod install

4. Quit Xcode and open the newly created workspace file - e.g. DemoProject.xcworkspace.

🚧

From this point onward, use the workspace (.xcworkspace) file, not the project (.xcodeproj) file.

📘

Update vs Install

If you already installed the Taboola SDK and just need to update the version - e.g. from 3.3.0 to 3.4.0 - you can use the update command:

1. Edit the Podfile (as described above) and change the version number.
2. Run: pod update.

See: pod install vs. pod update

Flow 3: Install with Carthage

Install Carthage on your system

If not already present, install Carthage on your system:

1. In the Mac terminal, use Homebrew to install Carthage:

$ brew update
$ brew install carthage

📘

This installation is required once per system.

Install Taboola SDK for your project

1. Using a text editor, open your Cartfile. Enter the Taboola SDK dependency, with an exact version number, and save:

binary "https://cdn.taboola.com/taboola-mobile-sdk/ios/carthage/TaboolaSDK.json" == <<iosSDKVersion>>

🚧

Make sure to indicate the latest version - e.g. <<iosSDKVersion>>.

2. Using the Mac terminal, run carthage update to build the framework.
3. In the Xcode project navigator, select the project node (top, left), and the General tab (right).
4. Scroll down to Frameworks, Libraries and Embedded Content and drag your TaboolaSDK.xcframework file into Xcode to add it.
5. Still within your project settings, select the Build Phases tab (top, right).
6. Click the + icon and select New Run Script Phase:

a. Specify your shell (e.g.: /bin/sh).
b. Add the following line to the script area (below the shell path):

$ /usr/local/bin/carthage copy-frameworks

$ /opt/homebrew/bin/carthage

🚧

Apple silicon machine

On an Apple silicon machine, Homebrew installs Carthage on a different path.

Use this path: /opt/homebrew/bin/carthage

c. Under Input Files, add the paths to the frameworks that you want to use. For example:

$(SRCROOT)/Carthage/Build/iOS/TaboolaSDK.xcframework

d. Under Output Files, add the paths to the copied frameworks. For example:

$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/TaboolaFramework.xcframework

Add the skAdNetwork ID for Taboola

With the release of iOS 14, you need to include the IDs of all your Ad Networks in Info.plist.

🚧

Requires Taboola SDK 3.2.0 or higher.

Method 1 (via the UI):

In Xcode:

1. Open Info.plist from the project navigator.
2. Next to the top-level key, click on Add (+):
   1. Enter SKAdNetworkItems as the new key's name.
   2. Select Array as the type.
3. Expand the newly created Array key (using the arrow).
4. Click on Add (+) and select Dictionary as the new key's type.

To add the Taboola Network ID:

1. Expand the newly created Dictionary key (using the arrow).
2. Click on Add (+):
   1. Enter SKAdNetworkIdentifier as the new key's name.
   2. Leave the type as String.
   3. Enter p4ybsjem3u.skadnetwork as the value.

Your newly created entries should like this:

📘

To add more Ad Networks, repeat the previous step:

• Enter SKAdNetworkIdentifier as the name of each new key.
• Enter the Ad Network's unique ID as the value of the key.

Method 2 (via XML):

Edit Info.plist in a text editor and add this code snippet:

<key>SKAdNetworkItems</key>
	<array>
		<dict>
			<key>SKAdNetworkIdentifier</key>
			<string>p4ybsjem3u.skadnetwork</string>
		</dict>
	</array>

Troubleshooting

iPhone simulator with Apple silicon

Problem

In some cases, when running the iPhone simulator with an Apple silicon machine, Xcode throws the following error:

building for iOS Simulator, but linking in dylib built for iOS, file '../TaboolaSDK.xcframework/TaboolaSDK' for architecture arm64

📘

This issue affects the simulator only - not real devices.

Resolution

To work around this problem, add arm64 to the excluded architectures for both your project and your Podfile.

Step 1: Update your project settings

Using Xcode:

1. Select the project within the project navigator (top, left).
2. Select the Build Settings tab (right). Make sure that the All tab (just below) is also selected.
3. Under Architectures, locate the Excluded Architectures node.
4. Next to the Debug or Release node, click on the + icon to add a new exclusion:
   • For the key, select Any iOS Simulator SDK.
   • For the value, type in arm64.

📘

Depending on your needs, add an exclusion under Debug or Release - or both.

5. Scroll down to the Build Options section, and locate the Validate Workspace node.
   • Set the value to Yes.

📘

Depending on your needs, set the value for Debug or Release - or both.

Step 2: Update your Podfile

Navigate to your project's ios directory, and edit your Podfile to include the following:

post_install do |installer|
  installer.pods_project.build_configurations.each do |config|
    config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
  end
end

Additional steps

If the above steps do not resolve the problem, you may need to:

• Update your existing pods (a sample script is provided below).
• clean and rebuild your project.

rm -rf ~/Library/Developer/Xcode/DerivedData/
pod deintegrate
pod update

🚧

The sample script

• Removes all build cache from Xcode.
• Updates all pods across your project.

💁🏻

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.