ayeT-Studios Publisher iOS (Swift) SDK Integration Guide (v1.7.1)



Updates

2020-08-11: v1.7.1 - Updated documentation to introduce new parametars to differentiate chargebacks from conversions
2020-07-29: v1.7 - Updated iOS SDK to xcframework, support for Xcode 12, Swift 5.x, iOS 11+, dropped ARMv7 support
2019-10-20: v1.6 - Updated iOS SDK to Xcode 11, iOS 13 SDK, Swift 5.1, full binary support
2019-07-19: v1.5 - Updated iOS SDK with adslot changes, recompiled with Swift 5, re-added x86_64 (simulator) support
2018-09-29: v1.4.2 - Updated iOS SDK to Xcode 10 and Swift 4.2, stripped debug symbols
2018-07-09: v1.4.1 - Removed Simulator Code from iOS SDK, fixed iTunes validation issues with Xcode 9+
2018-05-07: v1.4 - Framework recompiled with Swift 4.1
2018-03-08: v1.3 - You are able to use logs now in order to locate implementation problems
2018-01-20: v1.2 - Added functions that provide current user balances
2017-12-06: v1.0 - Initial Release of our Publisher SDK (iOS)


Introduction

The ayeT-Studios Publisher SDK allows you to easily monetize your app and reward your users with in-app currency. Your users get access to our offerwalls, allowing them to earn currency for completing tasks such as trying new apps, answering surveys, signing up for free trials or watching video ads. The integration is simple, allows both managed (our servers store user information and balances) and unmanaged (you receive callbacks and handle user wallets yourself) currencies and also works well alongside traditional in-app purchases.




Topics

  1. Prerequisites
  2. Download the library
  3. Add the library to your Xcode project
  4. Initialize the SDK & Receive Managed Balances
  5. Check User Balances (Managed Currency Handling)
  6. Show the Offerwall
  7. Logs
  8. Appendix I: Unmanaged Currency Handling / Conversion Callbacks





1. Prerequisites


Before integrating the SDK in your app, you should sign up for a publisher account. Afterwards login as publisher and create a new iOS App Placement using the correct (Xcode) bundleId you intend to use for your final app.
This is important since we'll generate an APP_KEY / Identifier for you which has to be added to SDK init call.

2. Download the library


You can download the lastest version of our publisher library here:
AyetStudiosSdk_v1.7.xcframework.zip (Swift 5.x compatible, Xcode 11/12, iOS 11+)

3. Add the library to your Xcode project


Unzip the downloaded xcframework archive file, preferably somewhere in your project root

Navigate to your project root in the Project Navigator, select General tab and then expand Frameworks, Libraries, and Embedded Content.
Click on the + sign and add the archive to your project, using Embed & Sign. The final configuration should look like this:


Please add the following to your Info.plist file:
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>	                

4. Initialize the SDK & Managed User Balances


You'll need to initialize Ayet SDK before being able to use it.
A good place to do this is the application:didFinishLaunchingWithOptions: method in your application delegate:
import AyetStudiosSDK
[...]
AyetSdk.sdkInit(appKey: "<your placement identifier from our dashboard>" , userIdentifier: "username (external identifier)" , callback: { available_currency , pending_currency , spent_currency in
    print("Available currency:  \(available_currency)")
    print("Pending currency:    \(pending_currency)")
    print("Spent currency:      \(spent_currency)")
});

If you want to spend user currency, for example if the user clicks a button assigned to a purchaseInAppItem function, you can utilize the deductBalance function:
@IBAction func purchaseInAppItem(_ sender: Any) {

    let deductAmount = 5

    AyetSdk.deductBalance(amount: deductAmount , deductCallback: {callback in

        if (callback.caseInsensitiveCompare("success") == .orderedSame) {
            print("Deduct response is successful");
            // TODO: activate the purchased content
        }
        else {
            print("Deduct response is unsuccessful");
            // this usually means that the user does not have sufficient balance in his account
        }
    })

}	                
The status string will be "success" if the balance deduction was successful or "failed" if something went wrong (e.g. insufficient user balance).

Attention: The username or external identifier passed in the init call (e.g. username, hashed email address, etc.) will be accessible in the conversion callbacks through the {external_identifier} parameter.

5. Check User Balances (Managed Currency Handling)


After initializing the SDK, you can check the current user balances anywhere in your code:

AyetSdk.getAvailableCurrency();

AyetSdk.getPendingCurrency();

AyetSdk.getSpentCurrency();	                

6. Show the Offerwall


Showing the offerwall is straight-forward, you can simply call showOfferwall from your UIViewController:

AyetSdk.showOfferwall(currentController: self, adslotName: "my offerwall adslot name");	                
showOfferwall starts our offerwall activity for the given adslot and displays available tasks for the user to complete.

7. Logs


If you want to see logs in Xcode debug area, simply call sdkLogEnable before initializing sdk.

AyetSdk.sdkLogEnable();	                

8. Appendix I: Unmanaged Currency Handling / Conversion Callbacks


If you want to manually manage your users currencies on your own servers, you can configure a conversion callback url in our publisher dashboard.
To do so, navigate to Placements / Apps, edit your app placement and set the Callback Url to your server's postback url:


If this is the callback url your set for your app placement:
https://your-server.com/callback?network=ayetstudios&amount={currency_amount}&uid={uid}&device={advertising_id}&payout_usd={payout_usd}

A typical conversion callback sent by our server will look like this:
https://your-server.com/callback?network=ayetstudios&amount=360&uid=username&device=[IDFA]&payout_usd=0.36
* Note: This assumes you set the user identifier to username in your AyetSdk.init(..) call, the currency conversion rate in your placement was 1000 per $1 and the user completed an offer with a $0.36 payout.

Important: Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.

Available Macros for Postback URLs:
{transaction_id}stringUnique transaction id - use for duplicate checks. If chargeback it's prepend with r-
{payout_usd}floatThe actual conversion payout in USD. If chargeback value is negative.
{currency_amount}floatThe amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.
{external_identifier} | {uid}stringThe user identifier set in your app for this user when initializing the sdk
{user_id}integerOur internal id for this offerwall user
{placement_identifier}stringThe placement_identifier for which the conversion occured
{adslot_id}intThe id of the adslot for which the conversion occured
{ip}stringConverting device's IP address if known, 0.0.0.0 otherwise
{offer_id}intOffer ID of the converting offer
{offer_name}stringName / title of the converting offer
{device_uuid}stringayeT-Studios internal device identificator
{device_make}stringDevice manufacturer
{device_model}stringDevice model
{advertising_id}stringDevice advertising id (GAID/IDFA) if known, otherwise empty
{sha1_android_id}stringDevice sha1 hashed android id if known, otherwise empty
{sha1_imei}stringDevice sha1 hashed imei if known, otherwise empty
{is_chargeback}intValues 0 or 1. Indicator if the callback is conversion or chargeback. If set to 0 then it's conversion else it's chargeback.
{chargeback_reason}stringReason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date}stringDate of chargeback creation. Only available if is_chargeback set to 1.


Postback Verification with HMAC Security Hash (optional):
Our server will always add a custom header, X-Ayetstudios-Security-Hash, containing a SHA256 HMAC hash of the request parameters and your publisher api key.
Your API key can be found in your dashboard at ayetstudios.com under settings.

To verify the hash, perform the following steps:
(1) Get all request parameters
(2) Order the request parameters alphabetically
(3) Build and compare the HMAC hash using the ordered request parameter string and your API key

PHP Example:
ksort($_REQUEST, SORT_STRING);
$sortedQueryString = http_build_query($_REQUEST, '', '&'); // "adslot_id=123&currency_amount=100&payout_usd=1.5...."
$securityHash = hash_hmac('sha256', $sortedQueryString, 'YOUR PUBLISHER API KEY');
if($_SERVER['HTTP_X_AYETSTUDIOS_SECURITY_HASH']===$securityHash) { // actually sent as X-Ayetstudios-Security-Hash but converted by apache2 in this example
    // success
}
else {
    // invalid signature
}                    


If your want to restrict postbacks to our callback server IPs, please whitelist the following IPs and check back regularly for possible changes:
35.165.166.40
35.166.159.131
52.40.3.140	    
Last IP List Update: 2017-04-07