Swift SDK
See how easy it is to integrate high-performance ads into your iOS app using our lightweight SDK.
Requirements
- iOS 14.0+
- Swift 5.9+
- Xcode 15+
Migration Guide
Migrating from 1.x to 2.x
A newAdsEvent.cleared event has been added. If you handle AdsEvent with an exhaustive switch statement without a default case, you must add a handler for .cleared.
Getting started
1. Installation
To get started, you will need to set up a publisher account to get a
publisherToken and code.Swift Package Manager (Recommended)
The Swift Package Manager is the simplest way to add dependencies to your iOS app. Once the package is set up, add KontextSwiftSDK to your list of dependencies.File > Add Package Dependencies ... and paste the URL into the search field.
CocoaPods
If you prefer using CocoaPods, add the following line to yourPodfile:
2. Initialize AdsProvider
Once the dependency has been added and resolved, you can import the SDK.
Next, create an instance of AdsProvider — the object responsible for managing ad loading and display. This is the most important part of the library, and it uses the previously created configuration.
eventPublisher property, which uses Combine for event streaming.
3. Set up IFA (Identifier for Advertisers)
The SDK automatically reads and forwards the IFA with each ad request once the user has granted permission. To enable this, you need to complete a one-time setup on each platform. Apple requires a usage description before the ATT (App Tracking Transparency) prompt can be shown. Add the following to yourInfo.plist:
By default, the SDK calls
ATTrackingManager.requestTrackingAuthorization automatically. To avoid App Store rejection, ensure the prompt is triggered at a natural point in your app flow (e.g. after onboarding) rather than immediately on launch.If your app manages the ATT prompt itself, set
requestTrackingAuthorization: false in AdsProviderConfiguration to prevent the SDK from showing a second prompt. You can then pass the resolved IDFA directly via the advertisingId parameter.4. Set up SKAdNetwork
SKAdNetwork (SKAN) is Apple’s privacy-preserving install attribution framework. To allow DSPs to measure ad conversions on iOS, you need to add their SKAdNetwork identifiers to yourInfo.plist.
The full list of required SKAdNetwork identifiers will be provided during onboarding. Make sure to add all of them, as missing an identifier means conversions from that DSP will not be attributed.
5. Prepare messages
Adapt your message object to provide the necessary information required for ad recommendations to work. You have two options: either make it conform toMessageRepresentable and return the respective properties, or make it conform to MessageRepresentableProviding and return a MessageRepresentable as a separate object. You can use the struct AdsMessage: MessageRepresentable for this purpose.
AdsProvider.
6. Show your first ad
The last step is to provide a place for the ads to appear. This is done by adding anInlineAdView to your view hierarchy, right after the corresponding message.
The view automatically handles loading and displaying the ad.
API documentation
AdsProvider properties
The configuration of the
AdsProvider.If set to true, ad generation will be disabled initially. It can later be enabled by calling
enable().Delegate that receives ad-related updates. Called on the main thread.
AdsProviderConfiguration properties
Your unique publisher token.
Unique identifier that remains the same for the user’s lifetime (used for retargeting and rewarded ads).
Email address of the user.
Unique ID of the conversation.
Placement codes enabled for the conversation. Example:
['inlineAd'].Character object used in this conversation.
The IDFA (Identifier for Advertisers) collected by your app. When provided, this value takes priority over the one automatically collected by the SDK. Use this together with
requestTrackingAuthorization: false when your app manages the ATT prompt itself.The IDFV (Identifier for Vendor) collected by your app. When provided, this value takes priority over the one automatically collected by the SDK. Falls back to
UIDevice.current.identifierForVendor when not set.Whether the SDK should automatically request ATT (App Tracking Transparency) authorization. Defaults to
true. Set to false if your app manages the ATT prompt itself to prevent the SDK from showing a second prompt.Publisher-provided identifier for the user cohort (for A/B testing).
Regulatory object used in this conversation.TCF (Transparency and Consent Framework) signals —
gdpr and gdprConsent — are handled automatically by the SDK if you have a TCF-compliant CMP (Consent Management Platform) integrated in your app. You do not need to set these manually.An arbitrary key-value collection of values that the publisher can send.
It varies per publisher, but all publishers should provide at least the
theme parameter.InlineAdView & InlineAdUIView properties
Advertisement object describing the ad.
AdsEvent types
filled
The ad is available or ads have changed.
Available advertisements.
cleared
Previously displayed ads have been removed. Triggered when a new user message
arrives and a fresh preload is in progress. Clear any currently displayed ads
from your UI when you receive this event.
noFill
adHeight
The height of a specific ad has been updated.
Advertisement whose height has changed after render.
viewed
The user has viewed the ad.
clicked
The user has clicked the ad.
renderStarted
Triggered before the first token is received.
renderCompleted
Triggered after the last token is received.
error
Triggered when an error occurs.
videoStarted
Triggered when the video playback starts.
videoCompleted
Triggered when the video playback finishes.
rewardGranted
Triggered when the user receives a reward.
event
Any other event. Payload is a dictionary.
Guides
Handling no-fill events
You get notified when the ad is not available by subscribing to thenoFill event.
Sizing the ad
Especially when using UIKit, the ad inside ofUITableView or UICollectionView needs to be sized properly to be displayed correctly. You get notified about ad height changes by subscribing to the adHeight event. Size changes multiple times as the ad gets rendered and ultimately stops at the final height.