iOS SDK

136 views 30/01/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 7,8 (up to Swift 3.2).
  • iOS 8.0+ target deployment.
  • armv7, arm64 devices, and the simulator.

Download YouAppi’s iOS SDK

Our latest SDK version can be downloaded as a ZIP file from the following URL:

YouAppi iOS SDK

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 'YouAppi_Framework', '~> 2.0'
    end
  • Open command line 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

  • 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 YouAppi.framework to the project’s Framework Search Paths setting.
  • Add the YouAppi.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 value of: 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}/YouAppi.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 YouAppi
  • Initialize SDK. 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.sharedInstance.initialize(accessToken: "<YOUR_APP_TOKEN>")
    }

    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: 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 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 <YouAppi/YouAppi-Swift.h>
  • Initialize SDK. Should be called only once in app life cycle. Best to call from AppDelegate:
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       [YouAppi initializeWithAccessToken:@"<YOUR-ACCESS-TOKEN>"];
    }

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

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 Make sure to show an ad as close as possible to loading 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 it can be expired by the time you show it (expiry time is 5 hours).
  • 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.

For SDK FAQ go here.

Tags: