Swift SDK

The Swift SDK from vektorone.co lets you integrate intelligent ad generation into your Swift-based chat or web systems. It enables you to:

• Send full chat history
• Retrieve contextual ads based on conversations or web page content
• Render ads in multiple formats (JSON, HTML, JavaScript)

All SDK functions use modern Swift async/await patterns with proper error handling.

Add the SDK to your Swift package:

// Package.swift
dependencies: [
    .package(url: "https://github.com/goodguysoft/adselect-swift.git", branch: "main")
]

Import in your application:

import Foundation
import NIO
import vektorone_sdk

• Swift: 5.9 or later
• Platforms: macOS 10.15+, iOS 13.0+, watchOS 6.0+, tvOS 13.0+
• Dependencies: SwiftNIO for async networking

Use `sendChatHistory()` to send complete conversation data to the API.

func sendChatHistory(
    apiId: String,
    apiKey: String,
    userID: String,
    conversationID: String,
    messages: [ChatMessage],
    eventLoopGroup: EventLoopGroup
) async throws

• `apiId` — Your VektorOne API ID (provided by support)
• `apiKey` — Your VektorOne API Key
• `userID` — Unique identifier for the human user receiving the ad
• `conversationID` — Unique identifier for the chat session
• `messages` — Array of message objects containing roles and text
• `eventLoopGroup` — NIO EventLoopGroup for async networking

struct ChatMessage {
    let role: String  // "User" or "Bot"
    let text: String  // Message content
}

• `role` — `“User”` (end user) or `“Bot”` (assistant, system, or agent)
• `text` — Message text content

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
 
let messages = [
    ChatMessage(role: "User", text: "I'm looking for dog food."),
    ChatMessage(role: "Bot", text: "We have natural dog food options.")
]
 
do {
    try await sendChatHistory(
        apiId: "YOUR_API_ID",
        apiKey: "YOUR_API_KEY",
        userID: "user-123",
        conversationID: "conv-456",
        messages: messages,
        eventLoopGroup: eventLoopGroup
    )
    print("Chat history sent successfully")
} catch {
    print("Failed to send chat history: \(error)")
}
 
// Always shutdown EventLoopGroup when done
try await eventLoopGroup.shutdownGracefully()

Use `getChatAd()` to fetch an ad based on chat context.

func getChatAd(
    apiId: String,
    apiKey: String,
    userID: String,
    conversationID: String,
    adType: String,
    jsFunc: String,
    eventLoopGroup: EventLoopGroup
) async throws -> String

• `apiId`, `apiKey` — Credentials provided by VektorOne support
• `userID` — Unique user identifier
• `conversationID` — Current chat session ID
• `adType` — Ad format (see constants below)
• `jsFunc` — JavaScript callback name (for JavaScript ad types only)
• `eventLoopGroup` — NIO EventLoopGroup for networking

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
 
do {
    let adHtml = try await getChatAd(
        apiId: "YOUR_API_ID",
        apiKey: "YOUR_API_KEY",
        userID: "user-123",
        conversationID: "conv-456",
        adType: Constants.adTypeHtmlText,
        jsFunc: "",
        eventLoopGroup: eventLoopGroup
    )
    print("Ad HTML: \(adHtml)")
} catch {
    print("Failed to get ad: \(error)")
}
 
try await eventLoopGroup.shutdownGracefully()

Use `getPageAd()` to retrieve an ad based on web page or article content.

func getPageAd(
    apiId: String,
    apiKey: String,
    pageContent: String,
    adType: String,
    jsFunc: String,
    eventLoopGroup: EventLoopGroup
) async throws -> String

• `apiId`, `apiKey` — Your API credentials
• `pageContent` — Raw HTML or text content of the page/article
• `adType` — Desired ad output format
• `jsFunc` — JavaScript callback name (for JavaScript ads only)
• `eventLoopGroup` — NIO EventLoopGroup for networking

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
 
let articleContent = """
# The Benefits of Gold Investments in 2025
 
Gold has long been considered a safe-haven asset and store of value...
"""
 
do {
    let adResult = try await getPageAd(
        apiId: "YOUR_API_ID",
        apiKey: "YOUR_API_KEY",
        pageContent: articleContent,
        adType: Constants.adTypeJsonText,
        jsFunc: "showAd",
        eventLoopGroup: eventLoopGroup
    )
    print("Generated ad: \(adResult)")
} catch {
    print("Ad generation error: \(error)")
}
 
try await eventLoopGroup.shutdownGracefully()

struct Constants {
    public static let adTypeJsonText        = "JsonText"
    public static let adTypeJsonImage       = "JsonImage"
    public static let adTypeHtmlText        = "HtmlTextAd"
    public static let adTypeHtmlImage       = "HtmlImageAd"
    public static let adTypeJavaScriptText  = "AdTypeJavaScriptText"
    public static let adTypeJavaScriptImage = "AdTypeJavaScriptImage"
    public static let adTypeBannerMediumRectJson  = "AdTypeBannerMediumRectJson"
    public static let adTypeBannerLeaderboardJson = "AdTypeBannerLeaderboardJson"
    public static let adTypeBannerWideSkyJson     = "AdTypeBannerWideSkyJson"
    public static let adTypeBannerMediumRectHtml  = "AdTypeBannerMediumRectHtml"
    public static let adTypeBannerLeaderboardHtml = "AdTypeBannerLeaderboardHtml"
    public static let adTypeBannerWideSkyHtml     = "AdTypeBannerWideSkyHtml"
}

All async functions use Swift's `async throws` pattern. Always handle errors using do-catch blocks:

do {
    let result = try await getPageAd(...)
    // Handle success
} catch {
    print("Error: \(error.localizedDescription)")
    // Handle failure
}

Important: Always create and properly shutdown EventLoopGroup instances:

// Create EventLoopGroup
let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
 
// Use for API calls...
 
// Always shutdown when done
try await eventLoopGroup.shutdownGracefully()

For multiple concurrent requests, consider using TaskGroup:

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
 
await withTaskGroup(of: Void.self) { group in
    group.addTask {
        do {
            let ad1 = try await getPageAd(..., eventLoopGroup: eventLoopGroup)
            print("Ad 1: \(ad1)")
        } catch {
            print("Error 1: \(error)")
        }
    }
 
    group.addTask {
        do {
            let ad2 = try await getPageAd(..., eventLoopGroup: eventLoopGroup)
            print("Ad 2: \(ad2)")
        } catch {
            print("Error 2: \(error)")
        }
    }
}
 
try await eventLoopGroup.shutdownGracefully()

Add delays between requests to avoid overwhelming the API:

for adType in adTypes {
    let ad = try await getPageAd(...)
    // 1 second delay between requests
    try await Task.sleep(nanoseconds: 1_000_000_000)
}

import Foundation
import NIO
import vektorone_sdk
 
@main
struct AdSelectDemo {
    static func main() async {
        let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
 
        let adTypes = [
            ("JSON Text Ad", Constants.adTypeJsonText),
            ("HTML Text Ad", Constants.adTypeHtmlText),
            ("JSON Image Ad", Constants.adTypeJsonImage)
        ]
 
        for (description, adType) in adTypes {
            print("Generating \(description)...")
 
            do {
                let adResult = try await getPageAd(
                    apiId: "YOUR_API_ID",
                    apiKey: "YOUR_API_KEY",
                    pageContent: "Sample article content...",
                    adType: adType,
                    jsFunc: "showAd",
                    eventLoopGroup: eventLoopGroup
                )
                print("✅ Success: \(adResult)")
            } catch {
                print("❌ Error: \(error)")
            }
 
            try await Task.sleep(nanoseconds: 1_000_000_000)
        }
 
        try await eventLoopGroup.shutdownGracefully()
        print("Demo completed!")
    }
}

• Getting Started
• API Reference
• Ad Formats
• Use Cases