Offerwall Integration for iOS SDK

Get up and running with the Offerwall Ad Unit in 4 easy steps:

Implement the Delegate
Initialize the Offerwall Unit
Present the Offerwall
Reward the User

Before You Start

Make sure that you have correctly integrated the ironSource SDK into your application. Integration is outlined here.

Step 1. Implement the Delegate

The ironSource SDK fires several events to inform you of Offerwall Activity and completions so you’ll know when to reward your users.
To receive these events, register to the delegate delegatesetOWDelegate:owDelegate:

OBJECTIVE-C

[[Supersonic sharedInstance] setOWDelegate:YOUR_OFFERWALL_DELEGATE];

SWIFT

let YOUR_OFFERWALL_DELEGATE:OWDelegate  = OWDelegate()

Note:

Note: Please do not assume the callbacks are always running on the main thread. Any UI interaction or updates resulting from ironSource callbacks need to be passed on to the main thread before execution.

The SDK will notify your delegate of all possible events listed below:

OBJECTIVE-C

@interface OWDelegate : NSObject <SupersonicOWDelegate>
@end
@implementation OWDelegate
/**
* Indicates that initiating the Offerwall was completed successfully
**/
- (void)supersonicOWInitSuccess{}
/**
* Will be triggered in case Offerwall was not able to initiate, for example:
* when there is no internet connection, servers are unavailable etc.
* @param error - will contain the failure code and description
**/
- (void)supersonicOWInitFailedWithError:(NSError *)error{}
/**
* Called each time the Offerwall successfully loads for the user
**/
- (void)supersonicOWShowSuccess{}
/**
* Called each time the Offerwall fails to show
* @param error - will contain the failure code and description
**/
- (void)supersonicOWShowFailedWithError:(NSError *)error{}
/**
* Called each time the user completes an offer.
* @param creditInfo - A dictionary with the following key-value pairs:
* @"credits" - (integer) The number of credits the user has Earned since the
* last supersonicOWDidReceiveCredit event that returned 'YES'. Note that the
* credits may represent multiple completions (see return parameter).
* @"totalCredits" - (integer) The total number of credits ever earned by the
* user.
* @"totalCreditsFlag" - (boolean) In some cases, we won’t be able to provide
* the exact amount of credits since the last event(specifically if the user
* clears the app’s data). In this case the ‘credits’ will be equal to the
* @"totalCredits", and this flag will be @(YES).
* @return The publisher should return a boolean stating if he handled this
* call (notified the user for example). if the return value is 'NO' the
* 'credits' value will be added to the next call.
**/
- (BOOL)supersonicOWDidReceiveCredit: (NSDictionary *)creditInfo{}
/**
* Called when the method
* ‘-getOWCredits’
* failed to retrieve the users credit balance info.
* @param error - the error object with the failure info
**/
- (void)supersonicOWFailGettingCreditWithError:(NSError *)error{}
/**
* Called when the user closes the Offerwall
**/
- (void)supersonicOWAdClosed{}
@end

SWIFT

class OWDelegate: NSObject, SupersonicOWDelegate {
/**
 * Indicates that initiating the Offerwall was completed successfully
**/
func supersonicOWInitSuccess(){}
/**
 * Will be triggered in case Offerwall was not able to initiate, for example:
 * when there is no internet connection, servers are unavailable etc.
 * @param error - will contain the failure code and description
**/
func supersonicOWInitFailedWithError(error:NSError){ }
/**
 * Called each time the Offerwall successfully loads for the user
**/
func supersonicOWShowSuccess(){}
/**
 * Called each time the Offerwall fails to show
 * @param error - will contain the failure code and description
**/
func supersonicOWShowFailedWithError(error:NSError){ }
/** 
 * Called each time the user completes an offer.
 * @param creditInfo - A dictionary with the following key-value pairs:
 * @"credits" - (integer) The number of credits the user has Earned since the
 * last supersonicOWDidReceiveCredit event that returned 'YES'. Note that the
 * credits may represent multiple completions (see return parameter).
 * @"totalCredits" - (integer) The total number of credits ever earned by the
 * user.
 * @"totalCreditsFlag" - (boolean) In some cases, we won’t be able to provide
 * the exact amount of credits since the last event(specifically if the user
 * clears the app’s data). In this case the ‘credits’ will be equal to the
 * @"totalCredits", and this flag will be @(YES).
 * @return The publisher should return a boolean stating if he handled this
 * call (notified the user for example). if the return value is 'NO' the
 * 'credits' value will be added to the next call.
**/
func supersonicOWDidReceiveCredit(creditInfo:NSDictionary){ }
/** 
 * Called when the method 
 * ‘-getOWCredits’ 
 * failed to retrieve the users credit balance info.
 * @param error - the error object with the failure info
**/
func supersonicOWFailGettingCreditWithError(error:NSError){ }
/**
 * Called when the user closes the Offerwall
**/
func supersonicOWAdClosed(){}
}

Step 2. Initialize the Offerwall Unit

Once the Offerwall Ad Unit is initialized, you will able to call functions on it. We recommend initializing the Offerwall on application launch.

OBJECTIVE-C

[[Supersonic sharedInstance] setOWDelegate:YOUR_OFFERWALL_DELEGATE];
[[Supersonic sharedInstance] initOWWithAppKey:APP_KEY withUserId:USER_ID];

SWIFT

Supersonic.sharedInstance().setOWDelegate(YOUR_OFFERWALL_DELEGATE)
Supersonic.sharedInstance().initOWWithAppKey(APP_KEY, withUserId: USER_ID)

Note: Note:

APP_KEY is the unique ID of your Application in your ironSource account.
USER_ID is the unique ID of your end user. We support NSString from 1 to 64 characters. Common practice is to use the Apple IDFV (Identifier for Vendor). More information on this User IDs can be found here.
Optional: The Offerwall supports additional parameters on the Init to customize your Offerwall request. See the Customized Parameters document for more information.

Step 3. Present the Offerwall

Once you receive the supersonicOWInitSuccess delegate you are ready to present the Offerwall to your user.

Note: If you’d like to use client-side callbacks, make sure to follow step 1 of the Automatic Client-Side Events below before you call showOW.

When you want to serve the Offerwall (typically after a user clicks on some in-app button), call the showOW method on your Supersonic instance:

OBJECTIVE-C

[[Supersonic sharedInstance] showOW];

SWIFT

Supersonic.sharedInstance().showOW()

New! Placements for Offerwall

With ironSource’s Ad Placements, you can customize and optimize the Offerwall experience. This tool enables you to present the Offerwall to your users in various places, i.e. in your in-app store, between levels, in the main menu, etc. You can use the below function to define the exact Placement to show the Offerwall. Navigate to the Ad Placement document for more details.

OBJECTIVE-C

[[Supersonic sharedInstance]showOWWithPlacement:placementName];

SWIFT

Supersonic.sharedInstance().showOWWithPlacement("PLACEMENT_NAME")

Step 4. Reward the User

ironSource supports two methods to reward your users. Select one of the following:

Server-Side Callbacks
Client-Side Callbacks

Method 1: Server-Side Callbacks

The default setting in your ironSource account notifies you of user’s completions or rewards via the supersonicDidReceiveCredit callback within the client of your app. Alternatively, you can turn on server-to-server callbacks to receive notifications to your back-end server. Once you select server-to-server callbacks you will not receive client-side notifications.

We recommend turning on server-to-server callbacks for Offerwall instead of client-side callbacks, as the authenticity of the callback can be verified. With server-to-server callbacks, you will have better control over the rewarding process as the user navigates out of your app to complete the offer.

Note: Note:

If you turn on server-to-server callbacks , remember not to reward the user more than once for the same completion.
We will fire a server-to-server callback to the selected location with an Event ID which is the unique identifier of the transaction. For us to know you’ve granted the user, you must respond to the callback with [EVENT_ID]:OK anywhere within the HTTP payload of the callback.
To utilize server-to-server callbacks, see here.

Method 2: Client-Side Callbacks

Proactive Polling API

You may call the function getOWCredits at any point during the user’s engagement with the app. You will then receive information on the user’s total credits and any new credits the user has earned.
See Step 1 for instructions on how to implement the protocol and receive callbacks for the following method:

OBJECTIVE-C

[[Supersonic sharedInstance] getOWCredits];

SWIFT

Supersonic.sharedInstance().getOWCredits()

Automatic Client-Side Events

You can receive client-side events automatically within your application by registering to the Offerwall delegate and setting the use of client-side callbacks. Setting automatic client-side callbacks will make sure that you’re notified about the user’s credit status at specific points in the Offerwall’s lifecycle. To do so:

Important! This code MUST be implemented before calling the initOWWithAppKey.

Import the Supersonic Configuration and set the use of client-side completion callbacks as follows
OBJECTIVE-C
```
#import <Supersonic/SUSupersonicAdsConfiguration.h>
```
SWIFT

No import required with Swift.
OBJECTIVE-C
```
[SUSupersonicAdsConfiguration getConfiguration].useClientSideCallbacks = [NSNumber numberWithInt:1];
```
SWIFT
```
SUSupersonicAdsConfiguration.getConfiguration().useClientSideCallbacks = NSNumber(int:1)
```
Once there is a completion event from the user the ironSource SDK will fire: (BOOL)supersonicOWDidReceiveCredit:(NSDictionary *)creditInfo event informing you of the completion.

Note: Note: If you are using automatic client-side events, we recommend adding the proactive polling method and checking the user’s reward status on app launch, upon in-app store entry and in the case a user opened the Offerwall, ardently verifying every 5 minutes after the user closes the Offerwall to ensure you don’t miss the latest update on the user’s rewards.

Done!

You are now all set to deliver Offerwall Ad Units in your application.

First Time Integration Tip

If this is a new integration for your application, your app will by default be in ‘Test Mode‘ on your ironSource dashboard. While your app is in Test Mode, the ironSource SDK will print more logs to the console in order to provide greater visibility into the SDK processes. To test your ad inventory, set up your Test Devices. Until you turn on live ad inventory, you will receive test campaigns that don’t generate revenue. Make sure to select Go Live! on the Ad Units page when your app is ready for live ad inventory.

What’s Next?
Follow our integration guides to implement additional Ad Units: