iOS SDK v4.3.6

Ofer Garnett YA

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
  • iOS 9.0+ target deployment.
  • armv7, arm64 devices, and the simulator.

Setup

Add the SDK to your project

    Automatic:SetupyourprojectwithCocoaPods”>Automatic: Setup your project with CocoaPodsYou 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 'YouAppiYagaMoatSDK', '4.3.6'
end
    • 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 YouAppiMoat.framework and YagaSDK.framework files to the “Frameworks” group of Xcode’s project navigator (like it is shown above). 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.
    • Make sure that Frameworks path is added to the project’s Framework Search Paths setting.
    • Add YouAppiMoat.framework and YagaSDK.framework to General → Embedded Binaries
    • Select YES inside the build settings under the option ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES.
    • Select 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. If your user is NOT subject to the GDPR rules, 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 (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:
    YouAppi.sharedInstance.ageRestrictedUser = true

    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. String 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:

    let adRequest=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.