iOS SDK Pre 8.1.x Integration


Before you begin:

  • Have you signed up for a Chartboost account?
  • Did you add an app to your dashboard?
  • Did you download the SDK 8.0.4?
  • Apps must be compiled with iOS base SDK v6.0 or higher.
  • As of June 1, 2016, Apple requires that all submitted apps support IPv6.
  • The Chartboost SDK runs only on devices with iOS version 6.0 or higher, iPhone 3GS or later, iPod 3rd generation or later, and iPad 2nd generation or later.
  • The bitcode version in iOS 10 is not backwards-compatible with Xcode v7.3.1. Please upgrade to Xcode v8.0+ to avoid bitcode compatibility errors, or disable bitcode in your Xcode v7.3.1 project.
startWithAppId must always be called during hard and soft bootups within the first few seconds of your app launching, regardless of any other actions or user interaction within your app.
Publishers should call the setPIDataUseConsent API from the Chartboost SDK and pass in the appropriate value for whether consent exists, does not exist, or is unknown. Publishers are required as part of Terms of Service to obtain the consent from their users before Chartboost will process any personal data and pass it to the Chartboost SDK via the above method. This method should be called before startWithAppId.

Drop Chartboost.framework into your Xcode project.

PRO TIP: Checkmark the Copy items if needed option. This creates a local copy of the framework for your project, which keeps your project organized.
CHAMoatMobileAppKit.framework is required when integrating a Chartboost SDK version below 8.0.3.

Add value -ObjC in Other Linker Flags under your project’s Build Settings for both Debug and Release.


Link the StoreKit, Foundation, CoreGraphics, WebKit, AVFoundation, and UIKit frameworks.


Add the import header #import <Chartboost/Chartboost.h> to your AppDelegate.m file.


Initialize Chartboost in your didFinishLaunchingWithOptions method.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions       
{
    // Initialize the Chartboost library
    [Chartboost startWithAppId:@"YOUR_CHARTBOOST_APP_ID" 
                  appSignature:@"YOUR_CHARTBOOST_APP_SIGNATURE" 
                      delegate:self];                     
    return YES;
}
startWithAppId must always be called during hard and soft bootups within the first few seconds of your app launching, regardless of any other actions or user interaction within your app.
You might receive a warning when passing an object as a delegate into the startWithAppID:appSignature:delegate: method. You can usually ignore this warning, but you can also resolve it by ensuring that the object you’re passing conforms to the ChartboostDelegate protocol.
Publishers should call the setPIDataUseConsent API from the Chartboost SDK and pass in the appropriate value for whether consent exists, does not exist, or is unknown. Publishers are required as part of Terms of Service to obtain the consent from their users before Chartboost will process any personal data and pass it to the Chartboost SDK via the above method. This method should be called before startWithAppId.

Add your app ID and app signature.

Chartboost App ID is a unique App identifier in our systems, therefore it is required to use a different Chartboost App ID per each app.

To show a static or video interstitial ad:

  • [Chartboost showInterstitial:CBLocationHomeScreen]; shows the interstitial at location HomeScreen. See Chartboost.h for available location options.
  • For customized control over how ads behave in your game, the Chartboost SDK also offers more features such as caching, delegate methods, and named locations.
  • Learn more about Chartboost video ads.
Chartboost calls should always be made from a main – not background – thread, or these calls may time out!
We strongly recommend that you cache your interstitials before showing them. Learn more about caching ▶
Prefetched videos (in total) only take up 30-50MB, even when you are using mediation.

To show a rewarded video ad:

  • [Chartboost showRewardedVideo:CBLocationMainMenu]; shows the rewarded video ad at location MainMenu. See Chartboost.h for available location options.
  • For customized control over how ads behave in your game, the Chartboost SDK also offers more features such as caching, delegate methods, and named locations.
  • Learn more about Chartboost video ads.
Chartboost calls should always be made from a main – not background – thread, or these calls may time out!
We strongly recommend that you cache your interstitials before showing them. Learn more about caching ▶
Prefetched videos (in total) only take up 30-50MB, even when you are using mediation.

To show a banner ad:

To make the banner ad show, first create it (detailed here), and then call the delegate method.
By default, a banner will automatically update its content on its own. The refresh default rate is 30s.
If you decide to disable banner auto-refreshing you can do that by setting the automaticallyRefreshesContent property to NO.

Test your integration.


Check the SDK icon in the Chartboost dashboard.

  • Go to your app’s App Settings > Basic Settings in your dashboard.
  • When our servers successfully receive a bootup call from our SDK using your app ID, the SDK icon underneath your app’s icon will turn from gray to green.

w00t! You just integrated the Chartboost SDK into your app!

Now you can start a campaign ▶


Check out more Chartboost SDK features

  • Caching: Speed up load times for ads by storing them locally on devices.
  • Chartboost Video: Add beautiful, high-quality video ads to give players the best in-game experience.
  • Named locations: Fine-tune your campaign targeting and ad frequency from the dashboard.
  • Delegate methods: Gain more control over how your game behaves around ads.
  • SDK configuration methods: Access Chartboost SDK functionality and settings.
  • Mediation: Show your ads along a waterfall of other top-quality networks.

Best practices

  • As noted in the iOS Human Interface Guidelines, it’s good practice to show interstitials only after the user has played your game for the first time.
  • You can use this Chartboost SDK delegate method to prevent interstitials until the second initialization call:
// For Chartboost SDKs v5.0+:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions       
{
    .
    .
    // Initialize the Chartboost library
    [Chartboost startWithAppId:@"YOUR_CHARTBOOST_APP_ID" 
                  appSignature:@"YOUR_CHARTBOOST_APP_SIGNATURE" 
                      delegate:self];
    // Prevent interstitials until after the user has played your game for the first time
    [Chartboost setShouldRequestInterstitialsInFirstSession:NO]
    .
    .
}


// For older Chartboost SDKs:
- (BOOL)shouldRequestInterstitialsInFirstSession {
    return NO;
}
startWithAppId must always be called during hard and soft bootups within the first few seconds of your app launching, regardless of any other actions or user interaction within your app.

▲ Back to top

The Chartboost SDK’s delegate methods allow you to exercise a greater degree of control over your integration. For example, you can:
  • Log debug messages when your game attempts to load an interstitial.
  • Prevent ads from showing the first time a user plays your game.
  • Determine whether a user has clicked an ad or just closed it – and react accordingly.
  • Prevent an interstitial page appearing when and where it would interfere with your game.
You can view the Chartboost iOS SDK methods at your disposal in the Chartboost.h header file in the Chartboost framework. You can see many of these methods in use within the sample project included with your iOS SDK download.  
▲ Back to top

Click here to view iOS SDK configuration methods.  
▲ Back to top

Before using any delegate functions, set the Chartboost delegate with delegate:self in your Chartboost initialization code:
#import <Chartboost/Chartboost.h>
#import <Chartboost/CBNewsfeed.h>
#import "AppDelegate.h"

@interface AppDelegate ()
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [self initializeStoryBoardBasedOnScreenSize];

    // Begin a user session.
    // Must not be dependent on user actions or any prior network requests.
    [Chartboost startWithAppId:@"YOUR_CHARTBOOST_APP_ID"
                  appSignature:@"YOUR_CHARTBOOST_APP_SIGNATURE"
                      delegate:self];

    return YES;
}
 
▲ Back to top

// Called before requesting an interstitial via the Chartboost API server.
- (BOOL)shouldRequestInterstitial:(CBLocation)location;

// Called before an interstitial will be displayed on the screen.
- (BOOL)shouldDisplayInterstitial:(CBLocation)location;

// Called after an interstitial has been displayed on the screen.
- (void)didDisplayInterstitial:(CBLocation)location;

// Called after an interstitial has been loaded from the Chartboost API
// servers and cached locally.
- (void)didCacheInterstitial:(CBLocation)location;

// Called after an interstitial has attempted to load from the Chartboost API
// servers but failed.
 - (void)didFailToLoadInterstitial:(CBLocation)location
                         withError:(CBLoadError)error;

// Called after an interstitial has been dismissed.
- (void)didDismissInterstitial:(CBLocation)location;

// Called after an interstitial has been closed.
- (void)didCloseInterstitial:(CBLocation)location;

// Called after an interstitial has been clicked.
- (void)didClickInterstitial:(CBLocation)location;
Don’t make cache or show calls inside didFailToLoad delegates or the universe will implode.
 
▲ Back to top

// Called after videos have been successfully prefetched.
- (void)didPrefetchVideos;

// Called before a rewarded video will be displayed on the screen.
- (BOOL)shouldDisplayRewardedVideo:(CBLocation)location;

// Called after a rewarded video has been displayed on the screen.
- (void)didDisplayRewardedVideo:(CBLocation)location;

// Called after a rewarded video has been loaded from the Chartboost API
// servers and cached locally.
- (void)didCacheRewardedVideo:(CBLocation)location;

// Called after a rewarded video has attempted to load from the Chartboost API
// servers but failed.
- (void)didFailToLoadRewardedVideo:(CBLocation)location
                         withError:(CBLoadError)error;

// Called after a rewarded video has been dismissed.
- (void)didDismissRewardedVideo:(CBLocation)location;

// Called after a rewarded video has been closed.
- (void)didCloseRewardedVideo:(CBLocation)location;

// Called after a rewarded video has been clicked.
- (void)didClickRewardedVideo:(CBLocation)location;

// Called after a rewarded video has been viewed completely and user is eligible for reward.
- (void)didCompleteRewardedVideo:(CBLocation)location
                      withReward:(int)reward;

// Implement to be notified of when a video will be displayed on the screen for
// a given CBLocation. You can then do things like mute effects and sounds.
- (void)willDisplayVideo:(CBLocation)location;
Don’t make cache or show calls inside didFailToLoad delegates or the universe will implode.
 
▲ Back to top

// Called after a cache call, either if an ad has been loaded from the Chartboost servers and cached, or tried to but failed.
- (void)didCacheAd:(CHBCacheEvent *)event error:(nullable CHBCacheError *)error

// Called after a showFromViewController: call, right before an ad is presented.
- (void)willShowAd:(CHBShowEvent *)event error:(nullable CHBShowError *)error;

// Called after a showFromViewController: call, either if the ad has been presented and an ad impression logged, or if the operation failed.
- (void)didShowAd:(CHBShowEvent *)event error:(nullable CHBShowError *)error;

// Called whenever the user clicks an ad to give a chance to the developer to present a confirmation gate before the click is handled.
- (BOOL)shouldConfirmClick:(CHBClickEvent *)event confirmationHandler:(void(^)(BOOL))confirmationHandler;

// Called after an ad has been clicked.
- (void)didClickAd:(CHBClickEvent *)event error:(nullable CHBClickError *)error;<

// Called when the link viewer presented as result of an ad click has been dismissed.
- (void)didFinishHandlingClick:(CHBClickEvent *)event error:(nullable CHBClickError *)error;
Learn more about Chartboost banner ads here.
 
▲ Back to top

// Called after the App Store sheet is dismissed, when displaying the embedded app sheet.
- (void)didCompleteAppStoreSheetFlow;

// Called after a click is registered, but the user is not forwarded to the App Store.
- (void)didFailToRecordClick:(CBLocation)location
                   withError:(CBClickError)error;

//Called after the SDK has been successfully initialized and video prefetching has been completed
- (void)didInitialize:(BOOL)status;
Don’t make cache or show calls inside didFailToLoad delegates or the universe will implode.
 
▲ Back to top

// Called after a Native Ad object has been loaded from the Chartboost API
// servers and cached locally.
- (void)didCacheInPlay:(CBLocation)location;

// Called after a Native Ad has attempted to load from the Chartboost API
// servers but failed.
- (void)didFailToLoadInPlay:(CBLocation)location
                  withError:(CBLoadError)error;
Don’t make cache or show calls inside didFailToLoad delegates or the universe will implode.
 
▲ Back to top

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions       
{
    //Set the consent status corresponding to the user's response using 
    // the [Chartboost setPIDataUseConsent:YES_BEHAVIORAL] method.
    [Chartboost setPIDataUseConsent:YesBehavioral];

    //Get the consent status via the (CBPIDataUseConsent)getPIDataUseConsent method.
    CBPIDataUseConsent currConsent = [Chartboost getPIDataUseConsent];

    // Initialize the Chartboost library
    [Chartboost startWithAppId:@"YOUR_CHARTBOOST_APP_ID" 
                  appSignature:@"YOUR_CHARTBOOST_APP_SIGNATURE" 
                      delegate:self];                     
    return YES;
}
▲ Back to top

// Decide if Chartboost SDK should block for an age gate.
+ (void)setShouldPauseClickForConfirmation:(BOOL)shouldPause;

// Called if Chartboost SDK pauses click actions awaiting confirmation from the user. Use
// to implement an age gate in your game.
- (void)didPauseClickForConfirmation;

// Confirm if an age gate passed or failed. When specified Chartboost will wait for
// this call before showing the IOS App Store.
+ (void)didPassAgeGate:(BOOL)pass;
Don’t make cache or show calls inside didFailToLoad delegates or the universe will implode.
 
▲ Back to top

These methods allow you to access Chartboost SDK functionality and settings. Choose a platform to view its methods.
  // Checks for a cached interstitial at given CBlocation.
  + (BOOL)hasInterstitial:(CBLocation)location;

  // Checks for a cached moreApps page at given CBlocation.
  + (BOOL)hasMoreApps:(CBLocation)location;

  // Checks for a cached rewarded video at given CBlocation.
  + (BOOL)hasRewardedVideo:(CBLocation)location;

  // Set to enable and disable the auto cache feature. Enabled by default.
  + (void)setAutoCacheAds:(BOOL)shouldCache;

  // Get the current auto cache behavior. Enabled by default.
  + (BOOL)getAutoCacheAds;

  // Set a custom identifier to send in the POST body for all Chartboost API server requests.
  + (void)setCustomId:(NSString *)customId;

  // Get the current custom identifier being sent in the POST body for all Chartboost API server requests.
  + (NSString *)getCustomId;

  // Decide if the Chartboost SDK should show interstitials in the first session.
  + (void)setShouldRequestInterstitialsInFirstSession:(BOOL)shouldRequest;

  //  Decide if the Chartboost SDK should show a loading view while preparing to display the MoreApps UI.
  + (void)setShouldDisplayLoadingViewForMoreApps:(BOOL)shouldDisplay;

  // Control whether the SDK downloads video creatives ahead of time for better performance. Enabled by default. If disabled, will severely impact the SDK’s ability to serve video ads!
  + (void)setShouldPrefetchVideoContent:(BOOL)shouldPrefetch;

  // Set to control how the fullscreen ad units should interact with the status bar. CBStatusBarBehaviorIgnore by default.
  + (void)setStatusBarBehavior:(CBStatusBarBehavior)statusBarBehavior;

  // Control how much information is logged in the console.
  + (void)setLoggingLevel:(CBLoggingLevel)loggingLevel;
Learn more about caching ▶
▲ Back to top