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

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"

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

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

YouAppi.initialize(accessToken, userConsent, gdpr)

YouAppi.sharedInstance.userConsent = true

YouAppi.sharedInstance.ageRestrictedUser = true