iOS SDK

963 views 16/07/2018 Shay Karpeles 0

Getting Started

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 9.
  • iOS 8.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'
    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 you 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.

Setup transport security settings for iOS9 and above

  • Add a new top level item to your info.plist called: NSAppTransportSecurity.
  • Under this item create a new sub item called: NSAllowsArbitraryLoads with a value: YES.
  • The XML in the info.plist should look like:
    <key>NSAppTransportSecurity</key>
             <dict>
                  <key>NSAllowsArbitraryLoads</key>
                  <true/>
             </dict>

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 example is shown for rewarded video, but similar to all ad units.

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)
}

Please note that <YOUR_APP_TOKEN> should be replaced with app token you will get from YouAppi.

  • 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 (YAAdInterstitialAdDelegate)
      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
    • Interstitial Video (YAAdInterstitialVideoDelegate)
      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 (YAAdRewardedVideoDelegate)
      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:YES];
}

Please note that <YOUR_APP_TOKEN> should be replaced with the app token you will get from YouAppi.

  • 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 (YAAdInterstitialAdDelegate)
      - (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)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
    • Interstitial Video (YAAdInterstitialVideoDelegate)
      - (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 (YAAdRewardedVideo)

      - (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

GDPR User Consent

The userConsent flag  value should be determined by the app developer according to the User’s response to a Consent Request and according to the user being subject to the GDPR rules (e.g.: a EU residence). The userConsent 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 response to the ad request, since the user cannot be detected and its 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)
  • User consent 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:

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 Name Description Value Type Provided by
{user_id} The unique identifier of the user to be rewarded. String Publisher
{reward_type} The name of the virtual item to be awarded. String Publisher
{reward_value} The number of credit units to be awarded to the user. Integer Publisher
{reward_id} A unique identifier of the commission event. String YouAppi

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

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

letadRequest=YAAdRequest()
adRequest.addCustomParam(paramKey: "{user_id}", paramValue: "user100")
adRequest.addCustomParam(paramKey: "{reward_type}", paramValue: "coins")
adRequest.addCustomParam(paramKey: "{reward_value}", paramValue: 25)
self.rewardedVideo?.adRequest=adRequest
self.rewardedVideo?.load()

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 bitbucket repository:

https://bitbucket.org/youappi/youappi-sdk-ios-demo-simple

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.

For SDK FAQ go here.

Tags: