IOS (Standard)

SDK Version: 4.5.0

For Swift documentation, please click here.

This document describes the basic procedure for integrating StartApp In-App Ads into your iOS applications.
After this simple integration process, StartApp In-App Ads enables you to reap the benefits of StartApp's In-App monetization products, which maximize the revenue generated by your application. All this profit-making is achieved with minimal effort and minimal interference with your users’ experience.

NOTES:
  • The code samples in this document can be copy/paste into your source code
  • You can also checkout our sample project here
  • When submitting your application to the App Store,do not forget to update your "IDFA Settings"
  • We strongly recommend you incorporate Integration Tests during the integration and before going live
  • A basic video tutorial is available here
  • If you have any questions, contact us via support@startapp.com

Getting Started

Step 1, Adding the SDK to Your Project

CocoaPods (Recommended)Manual

Open your project's Podfile and add this line to your app's target:

pod 'StartAppSDK'

Run pod install from command line:

$ pod install

If you're new to CocoaPods, see their official documentation (https://guides.cocoapods.org/using/using-cocoapods) for info on how to create and use Podfiles.

 

Step 2, Initialization

In your application delegate class (AppDelegate.m), import the StartApp SDK and add the following line to your application's didFinishLaunchingWithOptions function:

// AppDelegate.m

#import <StartApp/StartApp.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // initialize the SDK with your appID
    STAStartAppSDK* sdk = [STAStartAppSDK sharedInstance];
    sdk.appID = @"your app Id";

    return YES;
}

Replace "your app id" with your own value provided in the developers’ portal.
To find your application ID, click on the "Apps and Sites" tab on the left pane and choose the relevant ID from your app list:

Step 3, User Consent (GDPR)

StartApp requires you to pass user consent flag via the API as detailed herein below. The user consent flag indicates whether a user based in the EU has provided consent for ads personalization, collection and use of personal data. Based on this consent flag, StartApp will be able to use the data to target the most relevant ads to your users. If a user has not consented, we will not show personalized ads to this user.

IMPORTANT NOTES:
  • Collection of consent is only required in countries covered by GDPR (EU member states). Consent is not required for users that are based outside those countries.
  • We recommend you to pass the consent flag to StartApp right after initializing the SDK.
  • In case of any consent change during the lifetime of the user activity, you are required to re-submit the relevant consent flag to StartApp.
  • Older SDK versions (before 3.8.0): We'll continue to support them with showing ads. It’s important to know that in case you cannot update the SDK version and the user consent is false for GDPR users, do not initialize StartApp SDK for such users.

Use this method in case the user has consented:

[[STAStartAppSDK sharedInstance] setUserConsent:YES forConsentType:@"pas" withTimestamp:[[NSDate date] timeIntervalSince1970]];

Use this method in case the user has not consented:

[[STAStartAppSDK sharedInstance] setUserConsent:NO forConsentType:@"pas" withTimestamp:[[NSDate date] timeIntervalSince1970]];

NOTE:timestamp parameter should represent the specific time a consent was given by the user.

To make the process easier, we have added a consent window to our demo apps. Please follow the link to see demo projects.

iOS sample consent window:

Simulator_Screen_Shot_-_iPhone_6_-_2020-04-09_at_10.17.24.png

Splash Ad (recommended)

StartApp Splash Ad is a top performing ad unit, presenting the industry's highest CPM's

A Splash Ad is a full-page ad that is displayed immediately after the application is launched. A Splash Ad first displays a full page splash screen that you define (as described below) followed by a full page ad.

Adding the Splash Screen

In your application delegate class (AppDelegate.m), after initializing the SDK, call the [sdk showSplashAd]  method:

// AppDelegate.m

#import <StartApp/StartApp.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // initialize the SDK with your appID 
    STAStartAppSDK* sdk = [STAStartAppSDK sharedInstance];
    sdk.appID = @"your app Id";
	
    [sdk showSplashAd];  // display the splash screen

    return YES;
}

If you wish to customize or use a different splash screen, please refer to the Advanced Usage.

Interstitial Ads

Interstitial Ads are full page ads, displayed before or after a certain content page or action, such as upon entering a stage, between stages, while waiting for an action, upon exiting the application and more. When integrating this ad type you are open to get both Display or Video ads. Our optimization will auto-select the ad type that will generate the most revenue for you.

In order to show rewarded video ad in your app, follow the following steps:

First, declare STAStartAppAd instance:

// YourViewController.h

#import <StartApp/StartApp.h>
 
@interface YourViewController : UIViewController 
{
    STAStartAppAd* startAppInterstitialAd;    // ADD THIS LINE
} 

Use the "loadAdWithDelegate" method:

// YourViewController.m 

- (void)viewDidLoad {
    [super viewDidLoad];
    startAppInterstitialAd = [[STAStartAppAd alloc] init];
    [startAppInterstitialAd loadAdWithDelegate:self];
}

Then, you can implement the following method in order to get a callback when ad is loaded and ready to be shown:

- (void)didLoadAd:(STAAbstractAd*)ad;

Finally, add the following lines where you want to show the ad

[startAppInterstitialAd showAd];
IMPORTANT

Loading an ad might take a few seconds so it's important to show the ad as late as you can. In case you call showAd() while the ad hasn't been successfully loaded yet, nothing will be displayed. For example, if you'd like to show an ad after completing a game's level, the best practice would be to show the ad upon completing the level (for example in your viewDidDisappear() function). On the other hand, loading and showing the ad together at the beginning of the next level might result with a failure – as the ad might not have enough time to load.

 

Return Ad

The Return Ad is a new ad unit which is displayed once the user returns to your application after a certain period of time. To minimize the intrusiveness, short time periods are ignored. For example, the Return Ad won't be displayed if the user leaves your application to take a short phone call before returning.

Return ads are enabled and activated by default. If you want to disable this feature, simply do sdk.returnAdEnabled = NO as part of the initialization process, in your AppDelegate.m file:

// AppDelegate.m

#import <StartApp/StartApp.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
   // initialize the SDK with your appID
   STAStartAppSDK* sdk = [STAStartAppSDK sharedInstance];
   sdk.appID = @"your app Id";
   
   sdk.returnAdEnabled = NO;  // disable return ads

   return YES;
}

 

Rewarded Video Ads

Rewarded Ads are interstitial video ads that provide a reward to the user in exchange for watching an entire video ad. The reward might be in-app goods, virtual currency or any premium content provided by the application. Because users actually opt-in to watch a rewarded video and are granted with something valuable in return, Rewarded Ads are an effective and clean monetization solution for stronger user retention and keeping users engaged in your application for a longer amount of time.

In order to show rewarded video ad in your app, follow the following steps:

First, declare STAStartAppAd instance:

// YourViewController.h

#import <StartApp/StartApp.h>
 
@interface YourViewController : UIViewController 
{
    STAStartAppAd* startAppRewardedVideoAd;    // ADD THIS LINE
} 

Use the "loadRewardedVideoAdWithDelegate" method:

// YourViewController.m 

- (void)viewDidLoad {
    [super viewDidLoad];
    startAppRewardedVideoAd = [[STAStartAppAd alloc] init];
    [startAppRewardedVideoAd loadRewardedVideoAdWithDelegate:self];
}

Then, you can implement the following method in order to get a callback when the user completes watching the video and is eligible for getting the reward:

- (void) didCompleteVideo:(STAAbstractAd*)ad;

Finally, add the following line where you want to show the ad

[startAppRewardedVideoAd showAd];

Native Ads

A "Native Ad" is a raw representation of an ad without any pre-defined wrapping UI, which gives you the freedom to design and control the ad exactly as you want. Using Native Ads, you can design an ad experience that perfectly fits your application's scene, content and functionality.

For a full integration guide, please refer to "Advanced Usage" page.

Banner Ads

To display banners in your app, add a STABannerView to your application according to the following steps:

1. In the header file of your view controller, import STABannerView.h and STABannerSize.h and declare an STABannerView instance variable

// YourViewController.h

#import <UIKit/UIKit.h>
#import <StartApp/StartApp.h>

@interface YourViewController : UIViewController 
{
    STABannerView* bannerView;
}

2. Create and initialize the STABannerView and add it as a subView to the view where you want it to be displayed. Remember to release the bannerView object in your dealloc() function in case you're not using ARC in your project

// YourViewController.m

- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
     if (bannerView == nil) {
        bannerView = [[STABannerView alloc] initWithSize:STA_AutoAdSize
                                              autoOrigin:STAAdOrigin_Top     
                                            withDelegate:nil];
        [self.view addSubview:bannerView];
    }
}

- (void) dealloc
{
    // Don't release bannerView if you are using ARC in your project
    [bannerView release];  // Add this line
    [super dealloc];
}

The STA_AutoAdSize detects the width of the device's screen in its current orientation, and provides the optimal banner for this size.

NOTE:
  • You can find your "developerId" and "appId" the same way as in step 3 above
  • This example shows the banner at the top of the root view controller (self.view), but you can pass any other view where you want to show the banner

 

Positioning the banner

The origin of the banner is determined by the "autoOrigin" parameter which can receive one of the following values

Value Position Behavior
STAAdOrigin_Top Auto Top The banner will be centered and pinned to the top of the view. In case the view is a root view controller, the banner will be located under the status bar, if exists.
STAAdOrigin_Bottom Auto Bottom The banner will be centered and pinned to the bottom of the view.

If you wish to use a fixed origin for the banner, please refer to the "Advanced Manual"

MRec Ads

MRec is a 300X250 rectangular ad integrated within an app's layout. The ad will be refreshed automatically.

In order to integrate MRec ad inside your app, you should use the Banner implementation and initiate it with the specific size: STA_MRecAdSize_300x250.

Cover Ads

Cover is a 1200X628 rectangular ad integrated within an app's layout. The ad will be refreshed automatically.

In order to integrate Cover ad inside your app, you should use the Banner implementation and initiate it with the specific size: STA_CoverAdSize.

Updating your IDFA Settings

When submitting your application to the App Store you need to update its "Advertising Identifier (IDFA)" settings in order to comply with Apple advertising policy.

On the "Advertising Identifier" section:

  1. Choose "Yes" on the right pane
  2. Opt-in the "Serve advertisements within the app" checkbox
  3. Opt-in the confirmation checkbox under "Limit Ad tracking setting in iOS"

 

Testing the Integration

Before you publish your app with StartApp, we strongly recommend that you test your integration to ensure it is operating properly.

Turn on Test Mode by adding the following:

STAStartAppSDK* sdk = [STAStartAppSDK sharedInstance];
sdk.testAdsEnabled = YES;

Now you are all set to get test ads.

IMPORTANT NOTE:
    • You MUST turn off the test mode by removing the code above before going live or else your app will fail to monetize.

Helpful Log Information

StartApp SDK automatically prints key logs to the console. These logs provide useful information about the initialization and ad load life cycle. 

The following table capture these logs:

Scenario

Log Level

Log Message

The SDK successfully initialized with APP_ID

Info

StartApp SDK initialized with account id: %APP_ID%"

If appId was set empty or null

Error

Invalid app id passed to init. Please provide a valid app id.

If a publisher didn’t write needed permissions in the manifest file

Error

Please grant the mandatory permissions : INTERNET & ACCESS_NETWORK_STATE, SDK could not be initialized.

If an ad was successfully loaded, the placement AD_TYPE can be of following values depends on which ad has been loaded:

  1. VIDEO
  2. REWARDED_VIDEO
  3. INTERSTITIAL
  4. RETURN
  5. OFFER_WALL
  6. OFFER_WALL_3D
  7. BANNER
  8. MREC
  9. COVER
  10. BANNER_3D
  11. NATIVE

SPLASH

Info

Loaded %AD_TYPE% ad with creative ID - %ADID%"

if an ad failed to load, the AD_TYPE takes value from the previous ‘successful loaded’ column and ERROR_MESSAGE shows the reason which can be NO FILL

Error

Failed to load %AD_TYPE% ad %ERROR_MESSAGE%

if an impression was sent successfully

Info

Sending impression

if an impression wasn’t sent but the ad had been rendered, happens by different REASONs: if an ad was overlapped by an other view or an ad has been closed too quickly

Error

Dropped impression because %REASON%"

If an ad was closed by the user, pressed [X] button

Info

Closed Ad

If an ad was clicked by the user and click event has been sent

Info

Clicked Ad

if an ad was prevented from loading by the SDK according to feature 'explicit loading'. PLACEMENT can be of following values:

  1. INAPP_FULL_SCREEN
  2. INAPP_OFFER_WALL
  3. INAPP_SPLASH
  4. INAPP_OVERLAY
  5. INAPP_RETURN

Error

Failed to load %PLACEMENT% ad: NO FILL

Advanced Usage

For advanced usage, please refer to "Advanced Usage"

Was this article helpful?
0 out of 0 found this helpful