iOS SDK Integration Guide

v3.0.0iOS 15.0+

Upgrading from v2?

Version 3.0.0 changes how the SDK is initialized and how the player is set. See the iOS SDK v2 → v3 migration guide for a step-by-step upgrade path.

Requirements

Before You Begin

Account Requirements:

• You have an active AdGem Account
• You have added your app to your Account

App Approval:

• Your app has been approved in the AdGem system

Important

By default, your app will not have access to AdGem's offers until you complete the initial integration steps and your app is approved. Contact your dedicated Publisher Support Advocate with any questions about the approval process.

:::

Platform Requirements

iOS SDK Requirements

• iOS 15.0 or higher
• Swift 5 or Objective-C
• Xcode 14 or higher

ATT required for IDFA attribution

The SDK automatically includes the device IDFA on its requests so installs can be matched back to the click deterministically — but only if your app has already obtained App Tracking Transparency (ATT) authorization. The SDK does not display the ATT prompt itself.

To enable this, your app must:

1. Add an NSUserTrackingUsageDescription key to its Info.plist, and
2. Call ATTrackingManager.requestTrackingAuthorization before showing the Offerwall.

If ATT is not granted, the IDFA is omitted and attribution falls back to fingerprint matching and SKAdNetwork, which are far less reliable. Deterministic matching also requires the user to have allowed tracking in the advertised app, not just yours.

---

Integration

Step 0. Create an App Property in the AdGem Publisher Dashboard

Step 0: Create an App Property in AdGem

Before AdGem can populate offers, you need to create an App Property in the AdGem Dashboard.

1. Create a Publisher Account in the AdGem Publisher Dashboard
2. Register your App Property in Properties & Apps

Need Help?

Contact your dedicated Publisher Support Advocate if you have any questions about setting up your App Property.

Step 1. Install the AdGem iOS SDK

Add the AdGem SDK to your app with Swift Package Manager:

1. In Xcode, choose File > Add Package Dependencies…

2. Enter the package URL:

   https://github.com/AdGem/ios-sdk-package

3. Select the AdGemSdk library and add it to your app target. Swift Package Manager downloads and links the framework automatically.

Step 2. Initialize the AdGem SDK

All communication with the SDK happens via the AdGem class, so first add the import:

import AdGemSdk

Initialize the SDK once, as early as possible — typically in application(_:didFinishLaunchingWithOptions:). Pass your AdGem App ID (from the AdGem Publisher Dashboard) via AdGemConfiguration, replacing ADGEM_APP_ID:

AdGem.initialize(configuration: AdGemConfiguration(appId: "ADGEM_APP_ID"))

No Info.plist entry required

The App ID is supplied programmatically via AdGemConfiguration. The previous AdGemAppID Info.plist key is no longer used.

Step 3. Set the Delegate and Handle Events

Set the delegate to receive Offerwall and reward events:

AdGem.delegate = self

The following delegate methods are available:

Called when the Offerwall starts loading on the user's device:

func offerwallLoadingStarted() {}

Called when the Offerwall has finished loading on the user's device:

func offerwallLoadingFinished() {}

Called when the Offerwall has closed on the user's device:

func offerwallClosed() {}

Called if the Offerwall has failed to load due to an error:

func offerwallLoadingFailed(error: Error) {}

The error is an NSError in the AdGem.errorDomain (com.adgem.sdk) domain, and its code is one of the AdGemErrorCode values:

Code	Value	Meaning
notInitialized	1	showOfferwall() was called before initialize(configuration:) or after close()
notReady	2	The SDK is still initializing, no player has been set, or there is no window to present from
offerwallUnavailable	3	The Offerwall failed to load (e.g. no connectivity); the underlying error is available via NSUnderlyingErrorKey
internalError	4	An unexpected internal failure

Called to reward the user with your type of currency:

func offerwallRewardReceived(amount: Int) {}

Step 4. Set the Player ID

Setting the Player ID

IMPORTANT: The Player ID is Required

The player_id parameter must be set with a unique identifier for each user in your application. This identifies the player so that virtual currency can be attributed to their account via the postback request. The player ID must remain constant for each unique player to:

• Prevent players from completing an offer more than once
• Ensure players receive their rewards correctly

Missing Player ID

Tracking URL clicks that do not contain a player_id value will be redirected to a 404 error page.

Player ID Structure Requirements

Requirement	Details
Case	Letters must be lowercase
Characters	Alphanumeric characters, hyphens, and underscores only
Max Length	256 characters
Forbidden	Emojis, special characters, uppercase letters

Good Examples:

• abc-123-efg-456
• user_12345
• player-a1b2c3d4

Bad Examples:

• aBc-123-Efg-456 (contains uppercase)
• player@123! (contains special characters)
• user-😀 (contains emoji)

Once the player's identity is known — at startup or later (for example, after login) — set the player. This triggers the session and makes the Offerwall available. Calling setPlayer again with a different player ID switches the active player.

let metaData = AdGemPlayerMetadata.Builder(playerId: "abc123")
  .age(20)
  .gender(.male)
  .level(5)
  .placement(1000)
  .isPayer(true)
  .iapTotalUsd(10.0)
  .createdAt(someDateTime!)
  .customField1("custom_field_1")
  .customField2("custom_field_2")
  .customField3("custom_field_3")
  .customField4("custom_field_4")
  .customField5("custom_field_5")
  .build()

AdGem.setPlayer(metaData)

Step 5. Show the Offerwall

Once the player is set, present the Offerwall:

AdGem.showOfferwall()

The Offerwall is presented from the topmost view controller.

Step 6. Tear Down the SDK (optional)

Call close() to tear down the SDK — for example on user logout, or before re-initializing with a different App ID. After close(), call initialize(configuration:) again to use the SDK.

AdGem.close()

---

Additional Information

Sample Apps

Sample iOS applications with implementations in both Swift and Objective-C can be found on GitHub.

Advertising Identifier (IDFA)

The SDK forwards the IDFA only when your app has App Tracking Transparency authorization. To enable it, add an NSUserTrackingUsageDescription entry to your Info.plist and call ATTrackingManager.requestTrackingAuthorization from your app. The SDK never prompts the user itself.

Optional Parameters

note

All parameter names and their values are case-sensitive.

You can optimize your revenue potential by segmenting your users using the optional parameters available in the iOS SDK, such as age, gender, level, and custom fields. These values can be retrieved on each conversion postback and used to segment your audiences.

Postback Setup

If you have opted for a "Server Postback", on each successful offer completion by a user AdGem will send a server postback to your server. See Postbacks to learn more.