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. Instalation
To get started, you will need to set up a publisher account to get a
publisherToken and codeSwift Package Manager (Recommended)
The Swift Package Manager is integrated to Swift and is one of the easiest ways to add a dependency to an iOS app. Once the Swift Package is setup add KontextSwiftSDK into your list of dependencies.File > Add Package Dependencies ... and paste the URL into search.
CocoaPods
If you prefer CocoaPods instead. Add the following line to yourPodfile:
2. Initialize AdsProvider
Once you have the dependency added and resolved you should be able to import the SDK. Next,AdsProvider, the object responsible for managing the loading and displaying ads. This is the most important part of the library. It utilizes previously created configuration.
AdsProvider also exposes eventPublisher property for observing events using Combine.
3. Prepare messages
Adapt your message object to provide necessary information for the ads recommendation to work. You have two options, either make them conform toMessageRepresentable to return respective properties or to MessageRepresentableProviding and return the MessageRepresentable as a whole new object. There is struct AdsMessage: MessageRepresentable which you can use for this scenario.
4. Show your first ad
The last thing remaining is to provide place for the Ads to manifest into. This is done by placingInlineAdView into View hierarchy just after the associated message. The view will take care of loading the ad.
InlineAdUIView instead and refer to the ExampleUIKit app.
API documentation
AdsProvider properties
The configuration of the
AdsProvider.Session ID representing the current user session. If not provided, a new session ID will be generated.
If true, the ads generation will be disabled initially. Can be later enabled by calling
enable().Delegate to receive ads related updates. Called on a 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 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.