iOS SDK

3639 views 2019-11-10 Ofer Garnett 0

Getting Started

Latest iOS version: 5.0.0
Release date: 27-Nov 2019

This document details the process of integrating YouAppi’s SDK with your iOS app.

If you have any question you can email us to: support@youappi.com

Please note: YouAppi’s iOS SDK can be integrated with both Swift and Objective C projects.

Requirements

  • XCode 10.2.
  • iOS 9.0+ target deployment.
  • armv7, arm64 devices, and the simulator.

Setup

Automatic: Setup your project with CocoaPods

You can setup your project with YouAppi’s SDK automatically using CocoaPods.

Steps for using CocoaPods:

  • Make sure CocoaPods is installed on your Mac.
  • Make sure your project has a pod file.
  • Add to your pod file YouAppi’s framework:

    target 'MyApp' do
      pod ‘YouAppiMoatSDK’, '5.0.0' 
    end  
  • Open a terminal and change the current directory to your project directory.
  • Run the command:

    pod install

After YouAppi framework is setup for your project, you can move on to the integration section of the document.

Manual: Setup your project for YouAppi’s SDK

Add the SDK to your project

  • Download YouAppi latest SDK from: YouAppi iOS SDK
  • If you don’t have “Frameworks” groups in your project make sure to add it:
  • Drag the downloaded framework file into the “Frameworks” group of Xcode’s project navigator. In the displayed dialog, choose “Create groups” for any added folders. You can deselect “Copy items into destination group’s folder” to only reference the SDK and not copy it to your project:

Setup your build environment

  • Open “Build Settings” tab of your project.
  • Add the path of YouAppiMoat.framework to the project’s Framework Search Paths setting.
  • Add the YouAppiMoat.framework to General → Embedded Binaries

 

  • Change to YES inside the build settings under the option ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES.
  • Change to YES inside the build settings under the option DEFINES_MODULE.

Build and archive for Apple store

In order to build and archive your app for the Apple Store you need to add the following:

  • Go to your app target.
  • Select Build Phases.
  • Go to Run Script section (you can add it by pressing + button if it doesn’t exist).
  • Add the following line in the text box:

    "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/YouAppiMoat.framework/strip-frameworks.sh"
  • It should look like this:

Integrate with your code

Please, note, the example below is shown for rewarded video, but the code will be the same for interstitial ad, too:

Swift

  • Import YouAppi SDK:
    import YouAppiMoat
  • Initialize SDK:

Initialize should be called only once in app life cycle. Best to call from AppDelegate:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]? = nil) -> Bool {
    YouAppi.initialize(accessToken: "<YOUR_APP_TOKEN>", UserConsent : true, gdpr : false)
}

Please note that <YOUR_APP_TOKEN> should be replaced with app token you will get from YouAppi. If your user is NOT subject to the GDPR rules (e.g.: a EU residence), please,  make sure gdpr value is ‘false’ in order to get relevant ads. UserConsent is the user’s response to a dialog presented to the user asking for permission.

  • Create rewarded video instance and listen to rewarded video events by implementing YAAdRewardedVideoDelegate:
    override func viewDidLoad() {
        super.viewDidLoad()
     
        let rewardedVideo = YouAppi.sharedInstance.rewardedVideo("ad_unit_id") // Get an instance of a rewarded video ad interface.
        rewardedVideo?.delegate = self
    }
     
    func onLoadSuccess(adUnitId: String) {
      // Will be called when rewarded video was loaded successfully.
    } 
     
     
    func onRewarded(adUnitId: String) {
        // Will be called when user watched a full video and should be rewarded.
    }
  • Please note: YouAppi ad unit id is created and controlled by the app developer. The ad unit id later appears in reports and helps to analyze performance for each ad unit. Any arbitrary value can be selected for ad unit id as long as it follows these rules:
    • it should be constructed only from letters (lowercase, uppercase)
    • numbers
    • underscores.
  • Load rewarded video ad:

    rewardedVideo?.load()
  • Show rewarded video ad:
    rewardedVideo?.show()
  • Check rewarded video avaiability:

    Please note it is best to be notified when ad is available using the delegate method: onLoadSuccess.

    rewardedVideo?.isAvailable()

     

  • Full list of events

    • Interstitial Ad 
      onAdStarted(adUnitId: String) // Ad strarted showing
      onAdEnded(adUnitId: String) // Ad ended showing
      onLoadSuccess(adUnitId: String) // Ad was loaded successfully and ready to be shown
      onLoadFailure(adUnitId: String, errorCode: YAErrorCode, error: Error?) // Failed loading an ad
      onShowFailure(adUnitId: String, errorCode: YAErrorCode, error: Error?) // Failed showing an ad
      onCardShow(adUnitId: String) // Card is about to be shown
      onCardClose(adUnitId: String) // Card is closed
      onVideoStarted(adUnitId: String) // Video started showing
      onVideoEnded(adUnitId: String) // Video ended showing
    • Rewarded Video 
      onAdStarted(adUnitId: String) // Ad strarted showing
      onAdEnded(adUnitId: String) // Ad ended showing
      onLoadSuccess(adUnitId: String) // Ad was loaded successfully and ready to be shown
      onLoadFailure(adUnitId: String, errorCode: YAErrorCode, error: Error?) // Failed loading an ad
      onShowFailure(adUnitId: String, errorCode: YAErrorCode, error: Error?) // Failed showing an ad
      onCardShow(adUnitId: String) // Card is about to be shown
      onCardClose(adUnitId: String) // Card is closed
      onVideoStarted(adUnitId: String) // Video started showing
      onVideoEnded(adUnitId: String) // Video ended showing
      onRewarded(adUnitId: String) // User should be rewarded for watching video

Objective-C

  • Import YouAppi SDK:
    #import <YouAppiMoat/YouAppiMoat-Swift.h>
  • Initialize SDK:

Should be called only once in app’s life cycle. Best to call from AppDelegate:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   [YouAppi initializeWithAccessToken:@"<YOUR-ACCESS-TOKEN>" userConsent:true gdpr:false];
}

Please note that <YOUR_APP_TOKEN> should be replaced with the app token you will get from YouAppi. If your user is NOT subject to the GDPR rules (e.g.: a EU residence), please,  make sure userConsent value is ‘true’ in order to get relevant ads.

  • Listen to rewarded video events by implementing YAAdRewardedVideoDelegate:
    - (void)viewDidLoad {
           [super viewDidLoad];
     
           YAAdRewardedVideo *rewardedVideo = [[YouAppi sharedInstance] rewardedVideo:@"test_ad_id"]; // Get an instance of a rewarded video ad interface.
           rewardedVideo.delegate = self;
       }
     
    - (void)onLoadSuccessWithAdUnitID:(NSString * _Nonnull)adUnitID{
        // Will be called wwhen ad is loaded successfully.
    }
     
    - (void)onLoadFailure:(NSString *)adUnitID errorCode:(YAErrorCode*)errorCode
                    error:(NSError *)error{
        // Will be called when ad fails to load.
    }
     
    - (void)onRewardedWithAdUnitID:(NSString * _Nonnull)adUnitID{
        // Will be called when user watched a full video and should be rewarded.
    }

    Please note: ad unit id should be constructred only from letters (lowercase, uppercase), numbers and underscore.

  • Load rewarded video ad:

    [rewardedVideo load];
  • Show rewarded video ad:
    [rewardedVideo show]

    Check rewarded video availability:

    Please note it is best to be notified when ad is available using the delegate method: onLoadSuccess.

    [rewardedVideo isAvailable]
  • Full list of events

    • Interstitial Ad 
      - (void)onLoadFailureWithAdUnitID:(NSString * _Nonnull)adUnitID errorCode:(enum YAErrorCode)errorCode error:(NSError * _Nullable)error; // Failed loading an ad
      - (void)onShowFailureWithAdUnitID:(NSString * _Nonnull)adUnitID errorCode:(enum YAErrorCode)errorCode error:(NSError * _Nullable)error; // Failed showing an ad
      - (void)onVideoStartedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Video started showing
      - (void)onVideoEndedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Video ended showing
      - (void)onAdStartedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Ad strarted showing
      - (void)onAdEndedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Ad ended showing
      - (void)onLoadSuccessWithAdUnitID:(NSString * _Nonnull)adUnitID; // Ad was loaded successfully and ready to be shown
      - (void)onCardShowWithAdUnitID:(NSString * _Nonnull)adUnitID; // Card is about to be shown
      - (void)onCardCloseWithAdUnitID:(NSString * _Nonnull)adUnitID // Card is closed
    • Rewarded Video

      - (void)onRewardedWithAdUnitID:(NSString * _Nonnull)adUnitID; // User should be rewarded for watching video
      - (void)onLoadFailureWithAdUnitID:(NSString * _Nonnull)adUnitID errorCode:(enum YAErrorCode)errorCode error:(NSError * _Nullable)error; // Failed loading an ad
      - (void)onShowFailureWithAdUnitID:(NSString * _Nonnull)adUnitID errorCode:(enum YAErrorCode)errorCode error:(NSError * _Nullable)error; // Failed showing an ad
      - (void)onVideoStartedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Video started showing
      - (void)onVideoEndedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Video ended showing
      - (void)onAdStartedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Ad strarted showing
      - (void)onAdEndedWithAdUnitID:(NSString * _Nonnull)adUnitID; // Ad ended showing
      - (void)onLoadSuccessWithAdUnitID:(NSString * _Nonnull)adUnitID; // Ad was loaded successfully and ready to be shown
      - (void)onCardShowWithAdUnitID:(NSString * _Nonnull)adUnitID; // Card is about to be shown
      - (void)onCardCloseWithAdUnitID:(NSString * _Nonnull)adUnitID // Card is closed

Custom parameters and server-to-server callback (optional)

YouAppi SDK supports customer parameters and server-to-server callback. Custom parameters could be passed during the ad request and received upon user’s completion event as a part of the callback string (server-to-server completion callback).

Parameter NameDescriptionValue TypeProvided by
user_idA unique identifier of the user to be rewarded.StringPublisher
reward_typeA name of the virtual item to be rewarded.StringPublisher
reward_valueA number of credit units to be rewarded to the user.StringPublisher
reward_idA unique identifier of the commission event.StringYouAppi
dynamicUserIdA unique parameter to verify transaction that could be changed throughout the session.StringPublisher

Callback URL example:
http://www.app.com?appUserId={user_id}&RewardValue={reward_value}&RewardType={reward_type}&RewardId={reward_id}&DynamicUserId={dynamicUserId}

You can use AdRequestBuilder object to add custom parameters as <key, value> to your ad request before loading an ad. Please, see an example below:

let adRequest = AdRequestBuilder()
                    .addCustomParam(paramKey: "reward_type", paramValue: "coin")
                    .addCustomParam(paramKey: "reward_value", paramValue: "100")
                    .build()        
self.rewardedVideo?.adRequest=adRequest
self.rewardedVideo?.load()

Dynamic User Id

This optional parameter could be changed throughout the session and used to verify Rewarded Video transactions. To receive this parameter through the server-to-server completion callback, setDynamicUserId() method should be called before calling show(). This parameter will be received with the other custom parameters upon user’s completion event as a part of the server-to-server callback string.

YouAppi.sharedInstance.dynamicUserId = "best_user_ever"

Age and Gender support (optional)

In order to get better supply that allocated specifically to the user, user’s age and gender could be forwarded to our server throughout YouAppi SDK. You can use YAAdRequest object and setGender() / setAge() methods accordingly before loading ads.

let adRequest = AdRequestBuilder()
                    .setAge(age: "35")
                    .setGender(gender: Gender.Male)
                    .build()        
self.rewardedVideo?.adRequest=adRequest
self.rewardedVideo?.load()

Interstitial Ad Creative Types

You may choose what creative type you want to be used with your Interstitial Ad unit: video, static or all types. By default, Interstitial Ad unit uses all types of creatives. AdRequestBuilder object can be used to add creative type (Video, Static, All) to your ad request before loading an ad. Please, see an example below:

let adRequest = AdRequestBuilder()
                    .setCreativeType(.Static)
                    .build()        
self.interstitialAd?.adRequest=adRequest
self.interstitialAd?.load()

GDPR User Consent

The userConsent value should be determined by the app developer according to the User’s response to a Consent Request. The gdpr value should be set according to the user being subject to the GDPR rules (e.g.: an EU residence). The gdpr flag value signals to YouAppi the permission to process and store the user’s Personal Information (e.g.: Advertising ID and IP address). In case that the flag value is false, YouAppi may decide not to respond to the ad request, since the user cannot be detected and his actions cannot be attributed to the user and hence also to YouAppi and to the app developer.

GDPR user consent can be passed in the following ways:

  • It is mandatory to pass user consent in SDK init:
YouAppi.initialize(accessToken, userConsent, gdpr)
  • DoesGDPRApply can be set by using:
YouAppi.sharedInstance.userConsent = true
  • If the user is known to be in an age restricted class (e.g.: under the age of 16 in some countries or under the age of 13 in other countries ) then the age restricted indication should be passed:
YouAppi.sharedInstance.ageRestrictedUser = true

Load and Show best practices

  • Make sure to init the SDK as soon as the app starts. It might take few seconds to complete the init process.
  • Make sure to load the ad about 30 seconds before you want to show it since it takes time for the ad and assets to be prepared.
  • Make sure to show an ad as close as possible to load of an ad, in order to have a better fill rate and relevant ads.
  • Make sure not to wait too long before showing an ad, since the ad will be expired 5 hours after being called for. In other words, “show” must be performed no more than 5 hours after the “load”.
  • Use ad event listeners in order to be notified when an ad is ready to be shown.
  • Use ad event listeners to handle load and show.
  • Loading an ad too many times without showing it might cause YouAppi servers to block the SDK from requests.

Demo App

A demo app showing a simple usage of the SDK can be found in the following Github repository:

https://github.com/YouAppi/youappi-sdk-ios-demo

The demo app contains 3 modules:

  • AppDemo – Shows how to use YouAppi’s SDK
  • AppDemoAdMob – Shows how to use YouAppi’s SDK with AdMob adapter
  • AppDemoMoPub – Shows how to use YouAppi’s SDK with MoPub adapter

Please make sure to read the README.md file for further instructions.

Tags: