Skip to main content
Use the 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.
Your API key is in the app binary, and users can extract it. Use the key only for ad requests and feedback.

Install

  1. In Xcode, select File → Add Package Dependencies.
  2. Enter the package URL:
Or add the package to your Package.swift:
The SDK uses only Apple system frameworks (Foundation, SwiftUI, CryptoKit, and AppTrackingTransparency). It adds no third-party dependencies.

Quick start

  1. Make one Gravity instance with your API key. It requests test ads until you set production: true at go-live.
  2. Call gravity.getAds(...) with the conversation messages, the session ID, and the placements. Run it at the same time as your model call.
  3. Show the ad with SpecAdView.
You see the ad under the response. SpecAdView records the impression when the ad appears.

Constructor

getAds()

Pass the end user’s IP address as 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.
Pass a stable 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

Use sendFeedback() if you make your own feedback UI. It sends the request in the background and ignores errors.
For the reason values, see Ad feedback.

Full example: request ads during the model stream

FAQ

No. Use async let to start getAds() at the same time as your model call. getAds() never throws.
No. The SDK does not read the advertising identifier. If the user gave App Tracking Transparency consent, you can send it: extraDeviceFields: ["ifa": idfa].
iOS 15, macOS 12, tvOS 15, watchOS 8, and later.

Troubleshoot