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+
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. 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.
4. 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).
Unique ID of the conversation.
Placement codes enabled for the conversation. Example:
['inlineAd'].Character object used in this conversation.
Publisher-provided identifier for the user cohort (for A/B testing).
Device-specific identifier provided by the operating systems (IDFA).
Vendor-specific identifier provided by the operating systems (IDFV).
Regulatory object used in this conversation.
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.
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
Controlling when ads load
You can fine-tune ad frequency by controlling when newmessages are passed into AdsProvider. This allows you to adjust the ratio of ads to messages dynamically.
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.