Skip to content

iOS SDK Integration Guide

Product Deprecation

Previous SDK Version Deprecation

Effective July 1, 2025, we will be discontinuing support for all previous versions of our AdGem Offerwall SDK and our infrastructure will no longer support traffic from SDK versions prior to the current release version for iOS, v2.0.0. We strongly encourage all developers and partners to upgrade to the latest SDK version to ensure uninterrupted service and continued technical support. Our team will be available to provide migration guidance and answer any questions during this transition period. Please reach out to your dedicated Publisher Support Advocate or Integration Specialist for a smooth migration path to the newest SDK version.

Requirements

Before you Begin

  • You must have an active AdGem Account
  • You must add your App to your Account
  • The AdGem iOS SDK supports devices iOS 15.8 and higher
  • The AdGem iOS SDK can be integrated using Swift 5 or Objective-C and requires XCode 11+
  • In order for your app to have access to AdGem's offers, you will need to ensure your app is approved in the AdGem system. App setup and approval instructions can be found HERE. By default, your app will not be enabled on offers until you have completed the intital integration steps. Please reach out to your dedicated Publisher Support Advocate with any questions.

Integration

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

Create a Publisher Account in the AdGem Publisher Dashboard and register your App Property Properties & Apps. For more detailed instructions, please see the Setting up you App Property guide.

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 Swift Package Manager, but you can also download the framework and add it manually if you prefer.

  1. In Xcode, go to File > Add Package Dependencies...
  2. Enter the repository URL: 
    https://github.com/AdGem/ios-sdk-package
  3. Select the version rule (e.g., Up to Next Major Version)
  4. Click Add Package

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 Offer Wall in your project:

AdGem.showOfferwall()

Please note there is no need to store instance of AdGem globally. The SDK will cache its instance on a 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 users device:

func offerwallLoadingStarted() {}

Called when the offer wall has finished loading on the users device:

func offerwallLoadingFinished() {}

Called when the offer wall has closed on the users 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 (the unique identifier for a user)

Setting the playerid

IMPORTANT: Replacing playerid

The offerwall url must be modified to replace the dummy parameter {playerid} with your parameter that represents the unique player as used internally in your application. This identifies the player so that virtual currency can later be attributed to their account via the callback request. The player ID has to remain constant (for the unique player in your application) so that players are prevented from completing an offer more than once, and are able to receive their rewards.

NOTE: Missing playerid

Please note that tracking url clicks that do not contain a playerid value will be redirected to a 404 error page.

REQUIRED: Player ID Structure

All playerid values that you return should only use lowercase alpha numeric values. A good playerid value may look like: abc-123-efg-456, but should NOT look like: aBc-123-Efg-456.

Your playerid should be alphanumeric and should not include emojis or any special characters. The max character limit for the playerid value is 256.

  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)


Addtional Information

Sample Apps

Sample iOS applications with implementations both in 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