Skip to main content

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 and CocoaPods are two currently supported ways of integrating KontextSwiftSDK into your project. 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.
dependencies: [
    .package(url: "https://github.com/kontextso/sdk-swift", .upToNextMajor(from: "1.2.0")) /// Update to the latest version
]
Alternatively, you can use Xcode’s UI: File > Add Package Dependencies ... and paste the URL into the search field.

CocoaPods

If you prefer using CocoaPods, add the following line to your Podfile:
pod 'KontextSwiftSDK'
You can find the Podspec here.

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.
import KontextSwiftSDK

let character = Character(
  id: "character-1234",
  name: "John Doe",
  avatarUrl: "https://example.com/avatar.png",
  greeting: "Hello, how can I help you today?"
)

let regulatory = Regulatory(
  gdpr: 1,
  // ... other regulatory properties
)

let configuration = AdsProviderConfiguration(
  publisherToken: "<publisher-token>",
  userId: "user-1234",
  conversationId: "conv-5678",
  enabledPlacementCodes: ["inlineAd"],
  character: character,
  variantId: nil,
  advertisingId: "<IDFA>",
  vendorId: "<IDFV>",
  adServerUrl: nil,
  regulatory: regulatory,
  otherParams: ["theme": "dark"]
)

let adsProvider = AdsProvider(
  // Previously created configuration (immutable and publicly accessible if needed later)
  configuration: configuration,
  // Optional delegate for receiving events via the delegate pattern. 
  delegate: self
)
You can also observe ad-related events through the 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 to MessageRepresentable 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.
// 1) Conform directly to MessageRepresentable
struct MyChatMessage: MessageRepresentable {
	...
	/// Unique ID of the message
	var id: String { self.uuid.uuidString }
	/// Role of the author of the message (user or assistant)
	var role: Role { self.isUser ? .user : .assistant }
	/// Content of the message
	var content: String { self.messageContent }
	/// Timestamp when the message was created
	var createdAt: Date { self.date }
	...
}

// 2) Conform to MessageRepresentableProviding
// Useful if your model has name collisions or you prefer mapping fields in one place.
struct MyChatMessage: MessageRepresentableProviding {
	...
	var message: MessageRepresentable {
		AdsMessage(
			id: self.uuid.uuidString,
			role: self.isUser ? .user : .assistant,
			content: self.messageContent,
			createdAt: self.date
		)
	...	
}
Whenever your list of messages changes, pass the updated array to the AdsProvider.
adsProvider.setMessages(messages)

4. Show your first ad

The last step is to provide a place for the ads to appear. This is done by adding an InlineAdView to your view hierarchy, right after the corresponding message. The view automatically handles loading and displaying the ad.
@State private var ads: [Advertisement] = []

ZStack {
  ForEach(messages, id: \.uuid.uuidString) { message in
    VStack {
      MyChatMessageView(message)
      if let ad = ads.first, ad.messageId == message.id {
        // Display the advertisement
        InlineAdView(ad: ad)
      }
    }
  }
}.onReceive(adsProvider.eventPublisher) { event in
   // React to adsProvider events
	switch event {
    case .filled(let newAds):
      ads = newAds
    case .adHeight(let newAd):
      guard let index = ads.firstIndex(where: { $0.id == newAd.id }) else {
        return
      }
      ads[index] = newAd
    default:
      break
  }	
}
For UIKit usage, use InlineAdUIView instead and refer to the ExampleUIKit app.

API documentation

AdsProvider properties

configuration
AdsProviderConfiguration
required
The configuration of the AdsProvider.
isDisabled
boolean
If set to true, ad generation will be disabled initially. It can later be enabled by calling enable().
delegate
AdsProviderDelegate
Delegate that receives ad-related updates. Called on the main thread.

AdsProviderConfiguration properties

publisherToken
string
required
Your unique publisher token.
userId
string
required
Unique identifier that remains the same for the user’s lifetime (used for retargeting and rewarded ads).
conversationId
string
required
Unique ID of the conversation.
enabledPlacementCodes
array
required
Placement codes enabled for the conversation. Example: ['inlineAd'].
character
object
required
Character object used in this conversation.
variantId
string
Publisher-provided identifier for the user cohort (for A/B testing).
advertisingId
string
Device-specific identifier provided by the operating systems (IDFA).
vendorId
string
Vendor-specific identifier provided by the operating systems (IDFV).
regulatory
object
Regulatory object used in this conversation.
otherParams
dictionary
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
Advertisement object describing the ad.

AdsEvent types

filled

The ad is available or ads have changed.
ads
array
required
Available advertisements.

noFill

adHeight

The height of a specific ad has been updated.
ad
Advertisement
required
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 new messages 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 the noFill event.

Sizing the ad

Especially when using UIKit, the ad inside of UITableView 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.