Table of Contents ▼
- iOS Integration Guide
- Before you begin
- Linking frameworks
- Adding -ObjC value
- Linking additional frameworks
- Adding the import header
- Initializing Chartboost
- Adding your app ID and app signature
- Showing a static or video interstitial ad
- Showing a rewarded video ad
- Showing a banner ad
- Testing your integration
- Checking the SDK icon in the dashboard
- More SDK features
- Best practices
- iOS Delegate Methods
- iOS Configuration Methods
![]() |
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
|
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
|
![]() |
Link the
|
![]() |
Add the import header
|
![]() |
Initialize Chartboost in your
|
- (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. |
- Replace
YOUR_CHARTBOOST_APP_ID
andYOUR_CHARTBOOST_APP_SIGNATURE
with your app ID and app signature. - Where can I find my 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: |
[banner showFromViewController:self];
is the Chartboost delegate method to show banner ads.- Learn more about Chartboost banner ads.
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. |
- Build and run your project from Xcode on a device or Simulator.
- Use Test Mode to see if test ads show up.
- Why can’t I see ads in my game?
![]() |
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
Overview of iOS Delegate Methods
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.
SDK configuration methods
Click here to view iOS SDK configuration methods.
▲ Back to top
SDK delegate setup
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
Static & video interstitial delegate methods
// 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
▲ Back to top
didFailToLoad
delegates or the universe will implode.Rewarded video delegate methods
// 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
▲ Back to top
didFailToLoad
delegates or the universe will implode.Banner delegate methods
// 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
Misc. delegate methods
// 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
▲ Back to top
didFailToLoad
delegates or the universe will implode.Native ads delegate methods
// 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
▲ Back to top
didFailToLoad
delegates or the universe will implode.GDPR
- (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
Age gate delegate methods
// 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
▲ Back to top
didFailToLoad
delegates or the universe will implode.These methods allow you to access Chartboost SDK functionality and settings. Choose a platform to view its methods.
![]() |
SDK Configuration Methods for iOS |
// 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
Last Updated on June 24, 2020