IOS advanced usage

Interstitial Ads

Implementing interstitial ads with objects

You can implement interstitial ad as an object if you need to gain more control over your ads, like using callbacks or using multiple ads with different properties.

First, import the Start.io (Formerly StartApp) SDK in your view controller and add the following lines to the header file for each view in which you would like to show an ad

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

In your view controller init STAStartAppAd within the viewDidLoad() method and load it within the viewDidAppear() method. Remember to release STAStatAppAd object in your dealloc()method in case you're not using ARC in your project.

// YourViewController.m 

- (void)viewDidLoad {
    [super viewDidLoad];
    startAppAd = [[STAStartAppAd alloc] init];
}

- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [startAppAd loadAd];  // Add this line
}

- (void) dealloc {
    // Don't release startAppAd if you are using ARC in your project
    [startAppAd release];  // Add this line
    [super dealloc];
} 
Finally, add the following lines where you want to show the ad

[startAppAd showAd];

 

Implementing interstitial video ads with objects

We highly recommend using our Automatic mode, which automatically selects the best Interstitial Ad to display, meaning the type of Ads that will generate the most revenue for you. To add an automatic Interstitial Ad, please refer to Interstitial Ads.

If you wish to get Video ads only, add the following code to the appropriate place or places in which you would like to show the video ad:

Example:

startAppAd = [[STAStartAppAd alloc] init];

[startAppAd loadVideoAd];

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

[startAppAd showAd];

Using Interstitial delegates

Set your view controller as a delegate so it is able to receive callbacks from the interstitial ad.

1. Add the STADelegateProtocol to the header file

   @interface YourViewController : UIViewController 
   {
       STAStartAppAd* startAppAd;    
   } 

2. Use "withDelegate:self" when calling the loadAd function: [startAppAd loadAd:STAAdType_Automatic withDelegate:self]
3. Implement the following functions:

(void) didLoadAd:(STAAbstractAd*)ad;
- (void) failedLoadAd:(STAAbstractAd*)ad withError:(NSError *)error;
- (void) didShowAd:(STAAbstractAd*)ad;
- (void) failedShowAd:(STAAbstractAd*)ad withError:(NSError *)error;
- (void) didCloseAd:(STAAbstractAd*)ad;
- (void) didClickAd:(STAAbstractAd*)ad;

 

Banner Ads

Loading a Banner

You can load a banner without attaching it to a view, enabling you to attach it when available in a later stage:

 [banner loadAd]; 

Once banner is loaded, bannerAdIsReadyToDisplay: delegate method will be called.

Hiding your banner

You can hide and show your banner in run time, using showBanner and hideBanner methods:

[bannerView showBanner];
[bannerView hideBanner];

 

Controlling the size of your banner

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

Value	Size	Best fits for
STA_AutoAdSize	Auto-size (recommended)	detects the width of the device's screen in its current orientation, and provides the optimal banner for this size
STA_PortraitAdSize_320x50	320x50	iPhone/iPod touch in portrait mode
STA_LandscapeAdSize_480x50	480x50	iPhone/iPod touch in landscape mode
STA_MRecAdSize_300x250	300x250	iPhone/iPod touch, Medium Rectangle
STA_CoverAdSize	1200X628	iPhone/iPod touch, Cover
STA_PortraitAdSize_768x90	768x90	iPad in portrait mode
STA_LandscapeAdSize_1024x90	1024x90	iPad in landscape mode

Using banner delegates

Set your view controller as a delegate so it is able to receive callbacks from the banner ad.

1. Add the STABannerDelegateProtocol to the header file

@interface YourViewController : UIViewController 
{
    STABannerView* bannerView;  
}

2. Use "withDelegate:self" when initializing the STABannerView object:

bannerView = [[STABannerView alloc] initWithSize:STA_AutoAdSize 
                                     autoOrigin:STAAdOrigin_Top                 
                                     withDelegate:self];

3. Implement the following functions:

- (void) didDisplayBannerAd:(STABannerView*)banner;
- (void) failedLoadBannerAd:(STABannerView*)banner withError:(NSError *)error;
- (void) didClickBannerAd:(STABannerView*)banner;

 

Using a fixed origin for your banner

If you choose to locate the banner in a fixed origin rather than the view's top or bottom, simply pass the required origin point (x,y) upon initialization as explain in the following example

Locating your banner 100 pixels above the view's bottom:

bannerView = [[STABannerView alloc] initWithSize:STA_AutoAdSize 
                                    origin:CGPointMake(0, self.view.frame.size.height - 100) 
                                    withDelegate:nil];

To use a different banner origin in a specific layout, call the "setOrigin"/"setStartAppAutoOrigin" with the new origin value.

 

Changing the banner size and origin upon rotation

If you choose to manually control the banner's size & origin upon rotation, you can do it in the didRotateFromInterfaceOrientation function.

Example:

// YourViewController.m

- (void)didRotateFromInterfaceOrientation:(UIInterfaceOrientation)fromInterfaceOrientation {
    if (UIInterfaceOrientationIsPortrait(self.interfaceOrientation)) {
         [bannerView setOrigin:CGPointMake(0, 0)];
    } else {	
        [bannerView setOrigin:CGPointMake(0, 300)];
    }
    [super didRotateFromInterfaceOrientation:fromInterfaceOrientation];
}

 

Showing banners in UITableView

If you would like to load a banner into a UITableView instead of a general UIView, follow these instructions:

1. Declare an STABannerView instance variable in your UITableView class

@interface YourViewController ()
{
    STABannerView* bannerview;
}
@end

2. Override the cellForRowAtIndexPath method, and add the required code:

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    static NSString *CellIdentifier = @"Cell";
    UITableViewCell *cell=nil;
    cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    
    if (cell == nil)  {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault  reuseIdentifier:CellIdentifier]; 
    }
   
   
    // ADD THE FOLLOWING LINES
    if(bannerview == nil)
    {
        bannerview = [[STABannerView alloc] initWithSize:STA_AutoAdSize autoOrigin:STAAdOrigin_Top withDelegate:self]; 
    }
   
    [bannerview addSTABannerToCell:cell withIndexPath:indexPath atIntexPathRow:2 repeatEach:8];
   
    return cell;
}

Use the addSTABannerToCell method to set the banner's position and frequency:

• atIntexPathRow - set the cell where you want to show the banner
• repeatEach - set repetition frequency

In the above example, the banner will be displayed at the second cell, and will be repeated each 8 cells.

Splash Ad

Customizing Splash Screen

You can customize the appearance of your splash screen using the STASplashPreferences object, as describes below. In order to use splash preferences, use the showSplashAdWithPreferencesmethod when initializing the splash screen in your AppDelegate class.

For example - using splash preferences to choose template mode:

STASplashPreferences *splashPreferences = [[STASplashPreferences alloc] init];
splashPreferences.splashMode = STASplashModeTemplate;
[sdk showSplashAdWithPreferences:splashPreferences];

 

Splash Preferences API

The following API describes all customization options available for the splash screen.

• Splash screen mode
  Decide whether to use user-defined or template mode.

  Parameter: splashMode

  Values:
  STASplashModeUserDefined
  STASplashModeTemplate

  Usage:
  splashPreferences.splashMode = STASplashModeTemplate;

• Change splash image (for user-defined mode)

  Change the splash screen image, instead of using the default one.

  Parameter: splashUserDefinedImageName

  Usage:
  splashPreferences.splashUserDefinedImageName = @"MyImage";

• Choosing splash template (for template mode)

  Choose of of 6 pre-designed templates.

  Parameter: splashTemplateTheme

  Values:
  STASplashTemplateThemeDeepBlue
  STASplashTemplateThemeSky
  STASplashTemplateThemeAshenSky
  STASplashTemplateThemeBlaze
  STASplashTemplateThemeGloomy
  STASplashTemplateThemeOcean

  Usage:
  splashPreferences.splashTemplateTheme = STASplashTemplateThemeBlaze;

• Changing template's icon and title (for template mode)

  The SDK uses your default application's name and icon. You can choose however to use your own assets.

  Parameters:
  splashTemplateIconImageName
  splashTemplateAppName

  Usage:

  splashPreferences.splashTemplateIconImageName = @"MyIcon";
  splashPreferences.splashTemplateAppName = @"MyAppName";

• Enable/Disable loading indicator (for user-defined mode)

  Choose whether to display a loading indicator on the splash screen.

  Parameter: isSplashLoadingIndicatorEnabled

  Values:
  YES
  NO

  Usage:
  splashPreferences.isSplashLoadingIndicatorEnabled = YES;

• Choose loading indicator's type (for user-defined and template modes)

  Choose which loading indicator type to display: iOS default activity indicator or a "dots" loading indicator

  Parameter: splashLoadingIndicatorType

  Values:
  STASplashLoadingIndicatorTypeIOS
  STASplashLoadingIndicatorTypeDots

  Usage:
  splashPreferences.splashLoadingIndicatorType = STASplashLoadingIndicatorTypeDots;

• Change loading indicator's position (for user-defined mode)

  The loading indicator is displayed by default on the center of the screen. You can choose however to set a custom position.

  Parameter: splashLoadingIndicatorCenterPoint

  Values:
  CGPointMake(x, y)

  Usage:
  splashPreferences.splashLoadingIndicatorCenterPoint = CGPointMake(100, 100);

• Force landscape orientation (for user-defined and template modes)

  The SDK display the splash screen using the orientation supported by the application and the device real orientation. You can choose however to force landscape orientation.

  Parameter: isLandscape

  Values:
  YES
  NO

  Usage:
  splashPreferences.isLandscape = YES;

Integrating Native Ads

Initializing and Loading Native Ads

First, import the Start.io (Formerly StartApp) SDK in your view controller and add the following lines to the header file for each view in which you would like to use Start.io Native ad.

// YourViewController.h

#import <StartApp/StartApp.h>

@interface YourViewController : UIViewController 
{
    STAStartAppNativeAd *startAppNativeAd;    // ADD THIS LINE
} 

In your view controller, initialize STAStartAppNativeAd within the viewDidLoad() method and load the ad with your selected preferences.

// YourViewController.m 

- (void)viewDidLoad 
{
    [super viewDidLoad];
    startAppNativeAd = [[STAStartAppNativeAd alloc] init];
    [startAppNativeAd loadAd];
}

You can check if the ad has been loaded, using startAppNativeAd.adIsLoaded;.

Using Native Ad delegates

Set your view controller as a delegate so it is able to receive callbacks from the native ad.

1. Add the STADelegateProtocol to the header file

@interface YourViewController : UIViewController 
{
    STAStartAppNativeAd *startAppNativeAd;    
} 

2. Implement the following functions

- (void) didLoadAd:(STAAbstractAd*)ad;
- (void) failedLoadAd:(STAAbstractAd*)ad withError:(NSError *)error;

3. Load an ad using loadAdWithDelegate

[startAppNativeAd loadAdWithDelegate:self];

 

Using Native Ad Preferences

STANativeAdPreferences can be used to customize some of the native ad properties to suit your needs, such as the number of ads to load, the image size of the ad, or whether the image should be pre-cached or not. For a full description of the NativeAdPreferences object, please refer to Native Ad Preferences API.

In order to use the STANativeAdPreferences object, simply use it when loading the ad:

[startAppNativeAd loadAdWithNativeAdPreferences:pref]; 

Example: load a 150x150 ad and register for callbacks:

// YourViewController.m 

- (void)viewDidLoad 
{
    [super viewDidLoad];
    startAppNativeAd = [[STAStartAppNativeAd alloc] init];
    STANativeAdPreferences *pref = [[STANativeAdPreferences alloc]init];
    pref.primaryImageSize = 4;     // Select 1200x628 primary image
    pref.secondaryImageSize = 2;     // Select 150x150 secondary icon	
    pref.autoBitmapDownload = YES;    // When set to NO no images will be downloaded by the SDK
		
    [startAppNativeAd loadAdWithDelegate:self withNativeAdPreferences:pref]; 
} 

 

Using the Native Ad Object

After initializing and loading your STAStartAppNativeAd object, use the STANativeAdDetailsobject to get details of all returning ads. The STANativeAdDetails object provides access to each ad's details, such as the ad's title, description, image, etc. This object also provides methods for firing an impression once the ad is displayed, and for executing the user's click on the ad. For a full description of the STAStartAppNativeAd object, please refer to Native Ad Details API.

 

Example: get some details of the 1st ad.

STANativeAdDetails *adDetails = [startAppNativeAd.adsDetails objectAtIndex:1];
titleLabel.text=[[startAppNativeAd.adsDetails objectAtIndex:1] title];
descriptionLabel.text=[[startAppNativeAd.adsDetails objectAtIndex:1] description];
imageView.image=[[startAppNativeAd.adsDetails objectAtIndex:1] imageBitmap];

 

Tracking the native ad

The SDK will log the impression and handle the click automatically. Please note that you must register the ad's view with the ad object. To make all ad elements of the view clickable register it using:

[adDetails registerViewForImpressionAndClick:yourViewForClicksInterception);

 

Native Ad Preferences API

Parameter name	Description	Values
adsNumber	number of native ads to be retrieved	a number between 1-10
primaryImageSize	size of the primary image to be retrieved	Can take one of the following:  0 - image size of 72X72  1 - image size of 100X100 2 - image size of 150X150 3 - image size of 340X340  4 - image size of 1200X628
secondaryImageSize	size of the icon secondary image to be retrieved	0 - image size of 72X72  1 - image size of 100X100 2 - image size of 150X150 3 - image size of 340X340
autoBitmapDownload	Select the method for retrieving the ad's icon. You can get the icon's URL only, or pre-cache it into a bitmap object	"YES"=pre cached, "NO"=URL only
userLocation.latitude	the device's latitude	latitude
userLocation.longitude	the device's longitude	longitude

 

At the moment, sizes 5-6 can't be used together with sizes 0-4.

STA Native Ad Details API

Parameter name	Description	Return value
title	Get the Ad's title	NSString
description	Get the Ad's description	NSString
imageBitmap	Get the actual icon of the ad, according to the selected size (if autoBitmapDownload="YES")	UIImage
imageUrl	Get the primary image URL of the ad, according to the selected size (if autoBitmapDownload="NO")	NSString
secondaryImageBitmap	Get the actual secondary image of the ad, according to the selected size (if autoBitmapDownload="YES")	UIImage
secondaryImageUrl	Get the secondary image URL of the ad, according to the selected size (if autoBitmapDownload="NO")	NSString
category	Get the category of the ad in the App Store	NSString
adId	Get the ad's internal number (for communication with AM)	NSString
rating	Get the rating of the ad in the App Store. The rating range is 1-5	NSNumber
clickToInstall	Get the call to action for the ad (either "install" or "open"	NSString
callToAction	Get a short text to place on the "call to action" button\area	NSString

 

Using Ad Tags

You can add tags to your ad placements. A tag is simply a free style string identifier that can be attached to any ad. Ad Tags will help you optimize your monetization by finding the right balance between ads and the perfect ad-viewing experience for your users.

For example, if you implement couple of interstitial ads in different places in your application, you can give each of them a different tag, one of them could be "Level1Complete", the other "AfterScoresBoard", then, you can monitor which placement convert better and get more engagement from your users.

In order to add tags, you simply need to add them to the right places in your code:

Banner: create ad preferences, set ad tag to ad preferences. Then set ad preferences to your banner view

STAAdPreferences *adPreferences = [[STAAdPreferences alloc] init];
adPreferences.adTag = @"BannerAdTagRequest";
self.bannerView = [[STABannerView alloc] initWithSize:STA_AutoAdSize autoOrigin:STAAdOrigin_Bottom withDelegate:self];
[self.bannerView setAdPreferneces:adPreferences];
[self.view addSubview:self.bannerView];

Interstitials: create ad preferences, set ad tag to ad preferences. Then load interstitial ad with this ad preferences

STAAdPreferences* interstitialPrefs  = [[STAAdPreferences alloc] init];
interstitialPrefs.adTag = @"InterstitialAdTag";
self.interstitialAd = [[STAStartAppAd alloc] init];
[self.interstitialAd loadAdWithDelegate:self withAdPreferences:interstitialPrefs];

Native ads: create native ad preferences, set ad tag as well as other native ad preferences properties. Then load native ad with this native ad preferences

STANativeAdPreferences *nativeAdPrefs = [[STANativeAdPreferences alloc] init];
nativeAdPrefs.adTag = @"NativeAdTag";
...    
self.nativeAd = [[STAStartAppNativeAd alloc] init];
[self.nativeAd loadAdWithDelegate:self withNativeAdPreferences:nativeAdPrefs];

After getting traffic, you could see those tags in the portal reports automatically, without extra setup. For more information visit

Enjoy Higher eCPM with Demographic-Targeted Ads

If you know your user's gender, age or location, Start.io (Formerly StartApp) can use it to serve better-targeted ads which can increase your eCPM and revenue significantly.

Set Age and Gender

Upon initialization, after providing your AppId, use the following line:

sdk.preferences = [STASDKPreferences prefrencesWithAge:<USER_AGE> andGender:<USER_GENDER>];

• Replace <USER_AGE> with the user's real age
• Replace <USER_GENDER> with the user's real gender, using STAGender_Male or STAGender_Female.

Example:

// 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.preferences = [STASDKPreferences prefrencesWithAge:22 andGender:STAGender_Male];

    return YES;
}

 

Set Location

The location of the user is a dynamic property which is changed constantly. Hence, you should provide it every time you load a new Ad:

[startAppAd loadAdWithAdPreferences:[STAAdPreferences prefrencesWithLatitude: andLongitude:]];

Example:

- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [startAppAd loadAdWithAdPreferences:[STAAdPreferences prefrencesWithLatitude:37.3190383911 andLongitude:-121.96269989]];
}

 

Upgrading from an older SDK

1. Remove all old Start.io (Formerly StartApp) files (including all .h and .m files, StartApp.bundle and StartApp.framework).
2. Clean your project

3. Continue to add the new Start.io (Formerly StartApp)  SDK files to your project, as describes here.