Getting started on iOS

This page explains how to install the Smart Instream SDK into an iOS application. This is the first step to complete before delivering instream ads in your video content.

  1. Prerequisites
  2. App Tracking Transparency & IDFA
  3. App Privacy details
  4. App Transport Security
  5. Installation
    1. Installation with Cocoapods
    2. Installation with Swift Package Manager
  6. Location

Prerequisites

There are some prerequisites before installing the instream SDK.

  • You use Xcode 15.0 or higher.
  • Your app targets iOS 13.0 or higher for iOS apps, or tvOS 13.0 or higher for tvOS apps.
  • You installed Cocoapods on your computer.

App Tracking Transparency & IDFA

Starting with iOS 14, your application will have to ask for consent before tracking the user. This request for consent can be made through the use of the App Tracking Transparency framework.

The Smart Instream SDK makes use of the device IDFA during ad calls and will retrieve it automatically if your app have requested tracking consent (and if the user has accepted). If no user consent is available or if the user denied the request, the SDK will not send any advertising ID.

To keep access to the IDFA on iOS 14 devices, you must implement the App Tracking Transparency framework in your app. You can find more information about this integration in our samples or in Apple's official documentation.

App Privacy details

Apple now requires you to disclose user data that your app is collecting, and the purpose of this collection. You will need to provide these information when submitting a new app or and app update starting December 8th, 2020.

Since the Smart Instream SDK collects some user data, you MUST declare in addition to the data collected by your app!

You can find more information about the data collected by the Smart Instream SDK and how to answer Apple's questions on dedicated page:


App Transport Security

App Transport Security (ATS) is a feature to protect user privacy introduced in iOS 9. ATS will block every non HTTPS connections. It is enabled by default for iOS applications and enforces secure connections.

Eventhough the ad industry tends to full HTTPS support, it happens that some medias are not hosted on secured servers. To avoid your video ads being blocked by ATS you should configure exceptions in your app's Info.plist file.


Under App Transport Security Settings of your Info.plist, make sure you enable the exceptions for:

  • Allow Arbitrary Loads and
  • Allow Arbitrary Loads For Media


Your Info.plist should contains these keys:


<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSAllowsArbitraryLoadsForMedia</key>
    <true/>
    <key>NSAllowsArbitraryLoadsInWebContent</key>
    <true/>
</dict>

The NSAllowsArbitraryLoads exception is required to make sure your ads will not be blocked by ATS on iOS 9 whereas NSAllowsArbitraryLoadsForMedia will make sure your ads are not blocked on devices with iOS 10 and higher.

Installation

There is two official ways to install the Smart Instream SDK in your application's project:

Installation with Cocoapods

CocoaPods is a dependency manager for Swift and Objective-C Xcode projects. You can read Cocoapods official documentation for information on how to setup Podfiles.


  • Add in your project's Podfile the following line:
    pod 'Smart-Instream-SDK'
  • Open a terminal window and cd to your project's directory.
  • Then from the command line, run:
    $ pod install --repo-update

    This will install all the dependencies and frameworks required for the Smart Instream SDK to work.

  • You can now proceed with the integration of your ads directly within your project's workspace.

Installation with Swift Package Manager

Swift Package Manager is a dependency manager included by default into Xcode. It can be used to integrate third party libraries from a Git repository.


To integrate the Smart Instream SDK in your app using Swift Package Manager:

  • Choose File > Add Packages in Xcode menu bar to open the Swift Package Manager window
  • In the Swift Package Manager window, enter the following URL:
    https://github.com/smartadserver/swift-package-manager-instream-sdk.git
  • Choose the SDK version you want to use.

    We recommend Up to next major version: 7.0.0 -> 8.0.0

  • Click on the Add Package button.

    You can now proceed with the integration of your ads directly within your project's workspace.

Location

For ad targeting purposes, the Smart Instream SDK can automatically send the latest known user location, if already made available to the application (The Smart Instream SDK will never actively try to retrieve user location).
This automatic location retrieval is disabled by default, and you can enable as follows, provided that one of the location permissions is granted to the application, and that the User consent was properly collected for ad targeting purpose regarding his location.

		[SASConfiguration sharedInstance].allowAutomaticLocationDetection = YES;