GravitySDK Swift package to request Gravity ads from your app and show them in SwiftUI. This page describes version 1.1.1. For the terms on this page, see Core concepts.
Before you start
- Your app targets iOS 15, macOS 12, tvOS 15, watchOS 8, or later.
- You have a Gravity API key. Get it from your dashboard under Settings → Platform Settings.
Install
- In Xcode, select File → Add Package Dependencies.
-
Enter the package URL:
Package.swift:
Quick start
- Make one
Gravityinstance with your API key. It requests test ads until you setproduction: trueat go-live. - Call
gravity.getAds(...)with the conversation messages, the session ID, and the placements. Run it at the same time as your model call. - Show the ad with
SpecAdView.
SpecAdView records the impression when the ad appears.
Constructor
getAds()
userIP. The SDK sends it as device.ip. The SDK cannot detect the end user’s IP address by itself, so pass it when your server knows it.
The SDK collects device data (User-Agent, OS, device model, screen size, time zone, locale, and device type) and sends it with the request. The Device and Geography reports in your dashboard work with no extra code.
getAds() never throws. On a failure before an HTTP response, it returns an AdResult with no ads and status 0. AdResult has ads, status, elapsedMs, and error.
Model usage
The published SDK doesn’t have a model
usage option. To report model usage, send it in a direct HTTP request to the ad API: see Report model usage.userId, including for signed-out users. The default "anonymous" is excluded from per-user analytics. extraUserFields only accepts string values, so it can’t carry the nested user.tags object.
Placements
Show ads in SwiftUI
SpecAdView draws the placement design that Gravity manages, and shows a built-in card when no valid design is available. It records the impression and the click, shows the required ad label, and shows feedback buttons.
GravityAdView is the built-in card without server-rendered designs. It takes ad, gravity, sessionId, and showFeedback.
Custom renderer
If you show ads with your own UI, record the impression and the click yourself:Hash PII
To help attribution, send a hashed email and phone. The SDK hashes them on the device, so the raw values do not leave the device.Ad feedback
UsesendFeedback() if you make your own feedback UI. It sends the request in the background and ignores errors.
Full example: request ads during the model stream
FAQ
Does the ad request block my model response?
Does the ad request block my model response?
No. Use
async let to start getAds() at the same time as your model call. getAds() never throws.Does the SDK collect the IDFA?
Does the SDK collect the IDFA?
No. The SDK does not read the advertising identifier. If the user gave App Tracking Transparency consent, you can send it:
extraDeviceFields: ["ifa": idfa].Which OS versions does the SDK support?
Which OS versions does the SDK support?
iOS 15, macOS 12, tvOS 15, watchOS 8, and later.