iOS SDK

https://github.com/Try-Gravity/gravity-swift-sdk

dependencies: [
    .package(url: "https://github.com/Try-Gravity/gravity-swift-sdk", from: "1.0.0"),
]

import GravitySDK

// 1. Initialize (once, e.g. in your App or ViewModel)
let gravity = Gravity(apiKey: "pub_...", production: true)

// 2. Fetch ads in parallel with your LLM call
let messages = [
    Message(role: "user", content: "What's the best way to deploy a Postgres DB?"),
    Message(role: "assistant", content: "Here are some options...")
]

async let adResult = gravity.getAds(
    messages: messages,
    sessionId: "sess_abc123",
    userId: currentUser.id,
    placements: [.belowResponse()]
)

// Stream your LLM response...
let result = await adResult

// 3. Render
if let ad = result.ads.first {
    GravityAdView(ad: ad, gravity: gravity, sessionId: "sess_abc123")
}

Gravity(
    apiKey: String? = nil,       // defaults to GRAVITY_API_KEY env var
    apiUrl: String = "https://server.trygravity.ai/api/v1/ad",
    timeoutSeconds: TimeInterval = 3.0,
    production: Bool = false,    // false = test ads, no billing
    relevancy: Double = 0.2,     // 0.0–1.0 contextual match threshold
    excludedTopics: [String]? = nil
)

await gravity.getAds(
    messages: [Message],
    sessionId: String,
    userId: String = "anonymous",
    placements: [Placement],
    userIP: String? = nil,
    hashedIdentity: HashedIdentity? = nil,
    extraUserFields: [String: String]? = nil,
    extraDeviceFields: [String: Any]? = nil,
    production: Bool? = nil,
    relevancy: Double? = nil
) -> AdResult

// Convenience constructors
Placement.belowResponse()           // "below_response"
Placement.inlineResponse()          // "inline_response"
Placement.aboveResponse()           // "above_response"

// Custom
Placement(placement: "right_response", placementId: "sidebar")

import GravitySDK

struct ChatView: View {
    let response: String
    let ads: [AdResponse]
    let gravity: Gravity
    let sessionId: String

    var body: some View {
        VStack {
            Text(response)
            if let ad = ads.first {
                SpecAdView(
                    ad: ad,
                    gravity: gravity,
                    sessionId: sessionId
                )
            }
        }
    }
}

// Impression — fire once when the ad becomes visible
gravity.trackImpression(ad)

// Click — always use clickUrl, not url
if let clickUrl = ad.clickUrl, let url = URL(string: clickUrl) {
    UIApplication.shared.open(url)
}

import GravitySDK

let hashed = hashPII(email: user.email, phone: user.phone)

let result = await gravity.getAds(
    messages: messages,
    sessionId: sessionId,
    userId: user.id,
    placements: [.belowResponse()],
    hashedIdentity: hashed
)

// Thumbs up
gravity.sendFeedback(
    sessionId: sessionId,
    ad: ad,
    sentiment: .thumbsUp
)

// Thumbs down with reasons
gravity.sendFeedback(
    sessionId: sessionId,
    ad: ad,
    sentiment: .thumbsDown,
    reasons: ["not_interested", "irrelevant"]
)

import GravitySDK

class ChatViewModel: ObservableObject {
    let gravity = Gravity(apiKey: "pub_...", production: true)
    @Published var ads: [AdResponse] = []
    @Published var response = ""

    func send(messages: [Message], sessionId: String, userId: String) async {
        // Fire ad request in parallel
        async let adResult = gravity.getAds(
            messages: messages,
            sessionId: sessionId,
            userId: userId,
            placements: [.belowResponse()]
        )

        // Stream LLM response
        for await chunk in streamLLM(messages) {
            await MainActor.run { response += chunk }
        }

        // Append ads
        let result = await adResult
        await MainActor.run { ads = result.ads }
    }
}