iOS SDK Integration Guide

v2.0.0iOS 15.8+

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.8 or higher
• Swift 5 or Objective-C
• Xcode 11 or higher

Android SDK Requirements

• Android API level 28 (Android 9.0) or higher
• Target SDK 34 or higher
• Android Studio with Gradle support

Unity SDK Requirements

• Unity 2020.3 or higher
• iOS or Android build target configured
• For iOS: Xcode 11+
• For Android: Android Studio with Gradle

Web Offerwall Requirements

• Modern web browser with JavaScript enabled
• HTTPS-enabled website (recommended for production)
• Server-side postback endpoint

---

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

There are two ways to add the AdGem SDK to your iOS app. We recommend that you use the CocoaPods approach, but you can also download it and add it manually if you prefer.

CocoaPods Integration Method (Recommended)

1. Install CocoaPods (v1.9 or newer). You can find more information on how to install CocoaPods here.

2. Edit your Podfile and add the following line:

   pod 'AdGem'

3. Run pod install in your terminal window. CocoaPods will automatically download the framework and install it into your project.

Manual Download

1. Download the latest version of the AdGem iOS SDK v2.0.0

2. Drag the AdGemSdk.xcframework folder into the Frameworks, Libraries, and Embedded Content section in Xcode

Step 2. Configure the AdGem SDK

Add a new AdGemAppID key to the app's Info.plist file replacing ADGEM_APP_ID with your AdGem app ID from the AdGem publisher dashboard.

<key>AdGemAppID</key>
<integer>ADGEM_APP_ID</integer>

Step 3. Use the AdGem Class

All communication with the SDK happens via the AdGem class. In order to access it the following import directive is required:

import AdGemSdk

Use the AdGem class to show the Offer Wall in your project:

AdGem.showOfferwall()

note

There is no need to store an instance of AdGem globally. The SDK will cache its instance on the first call and will always return the same one for all subsequent calls to AdGem.

Step 4. Delegate Methods

The following delegate methods are available:

Called when the offer wall starts loading on the user's device:

func offerwallLoadingStarted() {}

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

func offerwallLoadingFinished() {}

Called when the offer wall has closed on the user's device:

func offerwallClosed() {}

Called if the offer wall has failed to load due to an error:

func offerwallLoadingFailed(error: Error) {}

Called to reward the user with your type of currency:

func offerwallRewardReceived(amount: Int) {}

Step 5. 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)

let metaData = AdGemPlayerMetadata.Builder
  .initWithPlayerId(playerId: "abc123")
  .playerAge(age: 20)
  .playerGender(gender: .male)
  .playerLevel(level: 5)
  .playerPlacement(place: 1000)
  .playerPayer(spentMoney: true)
  .playerIAPTotal(iapTotal: 10.0)
  .playerCreatedAt(creationDate: someDateTime!)
  .customField1(field: "custom_field_1")
  .customField2(field: "custom_field_2")
  .customField3(field: "custom_field_3")
  .customField4(field: "custom_field_4")
  .customField5(field: "custom_field_5")
  .build()

AdGem.setPlayerMetaData(metaData: metaData)

---

Additional Information

Sample Apps

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

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. Please visit Optional Parameters to learn more.

Postback Setup

If you have opted for a "Server Postback", on each successful offer completion by a user AdGem will send a GET request to your server. Please visit our guide on Server Postback Setup to learn more.

---

Updated on September 11, 2024