Delegate Methods

Overview

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.
• Determine when an ad is done loading and ready to be shown.
• Determine whether a user has clicked an ad or just closed it and react accordingly.

You can view the Chartboost iOS SDK methods at your disposal in the CHBAdDelegate.h header file in the Chartboost framework. You can see many of these methods in use within the Chartboost sample project.

📘

Note

All iOS 14 information can be found on Upgrading the SDK.

SDK Configuration Methods

See SDK Configuration Methods.

Ad Delegate Setup

In order to receive delegate method calls you need to set the ad's delegate:

CHBInterstitial *interstitial = [[CHBInterstitial alloc] initWithLocation:CBLocationDefault delegate:self];
// now self will receive delegate calls for the methods it has implemented

interstitial.delegate = anotherObject;
// now anotherObject will receive delegate calls for this ad instead of self

Ad Identifier

All the event objects passed as parameters in delegate method calls include an adID property. This is a string that uniquely identifies a cached ad and may assist in identifying faulty creatives when working with Chartboost.

Static & Video Interstitial Delegate Methods

didCacheAd

• Description: Called after a cache call if
  • an ad has been loaded from the Chartboost servers and cached.
  • an ad has failed to be loaded from the Chartboost servers.
• Parameter Event: A cache event with info related to the cached ad.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad is ready to be shown after the cache method has been called.

Example:

-void didCacheAd:(CHBCacheEvent *)event error:(nullable CHBCacheError *)error {
    if{
        // Handle error. Maybe trigger a retry mechanism.
    }
}
- (void)willShowAd:(CHBShowEvent *)event;

🚧

Caution

Don't make cache requests inside a didCacheAd:error or your app may enter an infinite loop which may cause, but not limited to, connectivity-issues and crashing.

willShowAd

• Description: Called after a showFromViewController: call, right before an ad is presented.
• Parameter Event: A show event with info related to the ad to be shown.
• Discussion: Get notified of when an ad is about to be presented.

Example:

-void willShowAd:(CHBShowEvent *)event {
    // Pause ongoing processes like video or gameplay.
}

didShowAd

• Description: Called after a showFromViewController: call, either if the ad has been presented and an ad impression logged, or if the operation failed.
• Parameter Event: A show event with info related to the ad shown.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified when the ad presentation process has finished.

Example:

-void didShowAd:(CHBShowEvent *)event error:(nullable CHBShowError *)error {
    if (error) {
        // Handle error, possibly resuming processes paused in willShowAd:
    }
}

shouldConfirmClick

• Description: Called whenever the user clicks an ad to give a chance to the developer to present a confirmation gate before the click is handled.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter confirmationHandler: A block to be executed only if the return value is YES. It takes a BOOL parameter that indicates if the confirmation gate was passed or not.
• Returns:
  • YES if the handling of the triggering click should be paused for confirmation.
  • NO if the click should be handled without confirmation.

    ❗️

    Warning

    If you return YES in your implementation make sure to execute the confirmationHandler at some point, since the ad flow will be paused until then. If you use the event's view controller to present a confirmation view make sure it has been dismissed by the time you execute the confirmationHandler.

• Discussion: If you return YES it is your responsibility to implement some confirmation method that triggers the execution of the confirmationHandler. If this method is not implemented, clicks will be handled without confirmation.

Example:

- (BOOL)shouldConfirmClick:(CHBClickEvent *)event confirmationHandler:(void(^)(BOOL))confirmationHandler
    if (self.needsClickConfirmation) {
        MyAwesomeAgeGate *ageGate = [[MyAwesomeAgeGate alloc] initWithCompletion:^(BOOL confirmed) {
            [ageGate dismissViewControllerAnimated:YES completion:^{
                confirmationHandler(confirmed);
            }];
        }];
        [event.viewController presentViewController:ageGate animated:YES completion:nil];
        return YES;
    } else {
        return NO;
    }
}

didClickAd

• Description: Called after an ad has been clicked.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad has been clicked. If the click does not result into the opening of a link, an error will be provided explaining why.

Example:

-void didClickAd:(CHBClickEvent *)event error:(nullable CHBClickError *)error {
    if (error) {
        // Handle error
    }
}

didFinishHandlingClick

• Description: Called when the link viewer presented as result of an ad click has been dismissed.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad click has been handled. This can mean an in-app web browser or App Store app sheet has been dismissed, or that the user came back to the app after the link was opened on an external application.

Example:

-void didFinishHandlingClick:(CHBClickEvent *)event error:(nullable CHBClickError *)error {
    if (error) {
        // Handle error
    }
}

didDismissAd

• Description: Called after an ad is dismissed.
• Parameter Event: A dismiss event with info related to the dismissed ad.
• Discussion: Get notified of when an ad is no longer displayed.

Example:

-void didDismissAd:(CHBCacheEvent *)event {
    // Resume processes paused in willShowAd:
}

Rewarded video delegate methods:

didCacheAd

• Description: Called after a cache call, either if an ad has been loaded from the Chartboost servers and cached, or tried to but failed.
• Parameter Event: A cache event with info related to the cached ad.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad is ready to be shown after the cache method has been called.

Example:

-void didCacheAd:(CHBCacheEvent *)event error:(nullable CHBCacheError *)error {
    if (error) {
        // Handle error. Maybe trigger a retry mechanism.
    }
}

willShowAd

• Description: Called after a showFromViewController: call, right before an ad is presented.
• Parameter Event: A show event with info related to the ad to be shown.
• Discussion: Get notified of when an ad is about to be presented.

Example:

-void willShowAd:(CHBShowEvent *)event {
    // Pause ongoing processes like video or gameplay.
}

didShowAd

• Description: Called after a showFromViewController: call, either if the ad has been presented and an ad impression logged, or if the operation failed.
• Parameter Event: A show event with info related to the ad shown.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when the ad presentation process has finished.

Example:

- (void)didShowAd:(CHBShowEvent *)event error:(nullable CHBShowError *)error {
    if (error) {
        // Handle error, possibly resuming processes paused in willShowAd:
    }
}

shouldConfirmClick

• Description: Called whenever the user clicks an ad to give a chance to the developer to present a confirmation gate before the click is handled.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter confirmationHandler: A block to be executed only if the return value is YES. It takes a BOOL parameter that indicates if the confirmation gate was passed or not.
• Returns:
  • YES, if the handling of the triggering click should be paused for confirmation.
  • NO, if the click should be handled without confirmation.

    ❗️

    Warning

    If you return YES in your implementation make sure to execute the confirmationHandler at some point, since the ad flow will be paused until then. If you use the event's view controller to present a confirmation view, make sure to dismiss it by the time you execute confirmationHandler.

• Discussion: If you return YES it is your responsibility to implement a confirmation method that triggers the execution of the confirmationHandler. If this method is not implemented, then clicks will be handled without confirmation.

Example:

- (BOOL)shouldConfirmClick:(CHBClickEvent *)event confirmationHandler:(void(^)(BOOL))confirmationHandler
    if (self.needsClickConfirmation) {
        MyAwesomeAgeGate *ageGate = [[MyAwesomeAgeGate alloc] initWithCompletion:^(BOOL confirmed) {
            [ageGate dismissViewControllerAnimated:YES completion:^{
                confirmationHandler(confirmed);
            }];
        }];
        [event.viewController presentViewController:ageGate animated:YES completion:nil];
        return YES;
    } else {
        return NO;
    }
 }

didClickAd

• Description: Called after an ad has been clicked.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad has been clicked. If the click does not result into the opening of a link, then an error will be provided explaining why.

Example:

- (void)didClickAd:(CHBClickEvent *)event error:(nullable CHBClickError *)error {
    if (error) {
        // Handle error
    }
}

- (void)didFinishHandlingClick:(CHBClickEvent *)event error:(nullable CHBClickError *)error;

didFinishHandlingClick

• Description: Called when the link viewer presented, as result of an ad click, has been dismissed.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad click has been handled. This can mean an in-app web browser or App Store app sheet has been dismissed, or that the user came back to the app after the link was opened on an external application.

Example:

- (void)didFinishHandlingClick:(CHBClickEvent *)event error:(nullable CHBClickError *)error {
   if (error) {
       // Handle error
   }
}

didDismissAd

• Description: Called after an ad is dismissed.
• Parameter Event: A dismiss event with info related to the dismissed ad.
• Discussion: Get notified of when an ad is no longer displayed.

Example:

- (void)didDismissAd:(CHBCacheEvent *)event {
   // Resume processes paused in willShowAd:
}

didEarnReward

• Description: Called when a rewarded ad has completed playing.
• Parameter Event: A reward event with info related to the ad and the reward.
• Discussion: Get notified when a reward is earned.

Example:

- (void)didEarnReward:(CHBRewardEvent *)event {
    // Update app internal state to reflect the earned reward
}

🚧

Caution

Don't make cache requests inside a didCacheAd:error or your app may enter an infinite loop which may cause, but not limited to, connectivity-issues and crashing.

Banner Delegate Methods

didCacheAd

• Parameter event: A cache event with info related to the cached ad.
• Parameter error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad is ready to be shown after the cache method has been called.

Example:

- (void)didCacheAd:(CHBCacheEvent *)event error:(nullable CHBCacheError *)error {
    if (error) {
        // Handle error
    } else {
        [event.ad showFromViewController:self];
    }
}
- (void)willShowAd:(CHBShowEvent *)event;

willShowAd

• Description: Called after a showFromViewController: call, right before an ad is presented.
• Parameter Event: A show event with info related to the ad to be shown.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad is about to be presented.

Example:

- (void)willShowAd:(CHBShowEvent *)event {
    // Make any necessary UI updates
}
- (void)didShowAd:(CHBShowEvent *)event error:(nullable CHBShowError *)error;

didShowAd

• Description: Called after a showFromViewController: call, either if the ad has been presented and an ad impression logged, or if the operation failed.
• Parameter Event: A show event with info related to the ad shown.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when the ad presentation process has finished.

Example:

- (void)didShowAd:(CHBShowEvent *)event error:(nullable CHBShowError *)error {
    if (error) {
        // Handle error
    } else {
        [event.ad cache];
    }
}
- (BOOL)shouldConfirmClick:(CHBClickEvent *)event confirmationHandler:(void(^)(BOOL))confirmationHandler;

shouldConfirmClick

• Description: Called whenever the user clicks an ad to give a chance to the developer to present a confirmation gate before the click is handled.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter confirmationHandler: A block to be executed only if the return value is YES. It takes a BOOL parameter that indicates if the confirmation gate was passed or not.
• Returns:
  • YES, if the handling of the triggering click should be paused for confirmation.
  • NO, if the click should be handled without confirmation.

    ❗️

    Warning

    If you return YES in your implementation make sure to execute the confirmationHandler at some point, since the ad flow will be paused until then. If you use the event's view controller to present a confirmation view make sure it has been dismissed by the time you execute the confirmationHandler.

• Discussion: If you return YES it is your responsibility to implement a confirmation method that triggers the execution of the confirmationHandler. If this method is not implemented, then clicks will be handled without confirmation.

Example:

- (BOOL)shouldConfirmClick:(CHBClickEvent *)event confirmationHandler:(void(^)(BOOL))confirmationHandler
    if (self.needsClickConfirmation) {
        MyAwesomeAgeGate *ageGate = [[MyAwesomeAgeGate alloc] initWithCompletion:^(BOOL confirmed) {
            [ageGate dismissViewControllerAnimated:YES completion:^{
                confirmationHandler(confirmed);
            }];
        }];
        [event.viewController presentViewController:ageGate animated:YES completion:nil];
        return YES;
    } else {
        return NO;
    }
}
- (void)didClickAd:(CHBClickEvent *)event error:(nullable CHBClickError *)error;

didClickAd

• Description: Called after an ad has been clicked.
• Parameter Event: A click event with info related to the ad clicked.
• Parameter Error: An error specifying the failure reason, or nil if the operation was successful.
• Discussion: Get notified of when an ad has been clicked. If the click does not result into the opening of a link, then an error will be provided explaining why.

Example:

- (void)didClickAd:(CHBClickEvent *)event error:(nullable CHBClickError *)error {
    if (error) {
        // Handle error
    }
}