Docs

Ad Kit iOS

Ad Kit allows developers to monetize their app with the Snap Audience Network. This feature is not available to all developers. Please apply for access here.


Requirements


Important Information

Testing Outside the US
  • Confirm the tester is using a US-based proxy/VPN.
  • Confirm the tester is using a device that does not have Snapchat installed.
    • If the device ever had Snapchat installed, the tester must rotate the IDFA.
  • If Snapchat is currently installed, delete Snapchat and rotate the IDFA.
Troubleshooting
  • We have a several validations in place. The most notable, is the US-based IP check.
  • The SDK will not re-attempt initialization for 24h after a failure due to ineligibility.
    • You can avoid the 24h delay by deleting the test app and reinstalling.
  • Outside the US? You'll need to VPN to a US-based ip address to successfully initialize the SDK
  • The recommended test plan is:
    • Delete Snapchat if it's installed on the device.
    • Rotate the IDFA.
    • Install the test app with the SDK.
    • VPN to US-based IP address before trying to initialize.
  • Still having trouble? Please reach out to your Partner Manager or adkit-support@snapchat.com
Test Ad Slot IDs

While building your integration, please test your code only with our designated Test Ad Slot IDs:

Test Slot IDExpected Ad ResponseFormat
01aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns App Install Video AdInterstitial
02aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns App Install Image AdInterstitial
03aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Display Video AdInterstitial
04aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Display Image AdInterstitial
05aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Web View Video AdInterstitial
06aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Web View Image AdInterstitial
07aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Video Ad with Small FormatsRewarded Video Banner Medium Rectangle
90ffffff-ffff-ffff-ffff-ffffffffffffNo Ad was returned from the server {SUCCESS with no-fill ad response (no ad could be found)}

Getting Started

Step 1: Create an App via Snap Kit

To get started with Ad Kit, you will need to create an app via Snap Kit and generate an app ID.

In order to create an app, you need a Snapchat account. If you are new to Snapchat, download Snapchat on your device and create a new account. Make sure to link an email to your account, as it is required to log in to the Snap Kit portal.

Once you have a Snapchat account, log in to the Snap Kit portal and click on the highlighted icon to add your application:

Then, name your application and save. Note: If you are only integrating Ad Kit to your app, toggle off Bitmoji avatar and Story Studio API.

Once you have created your app, your snapKitAppId will show up as a string in the URL, i.e. 8944b384-432f-4075-92e0-fe4b8682a0aa. Copy and save this value.

Step 2: Import the SDK

Once your application, created on the Snap Kit developer portal, is approved, import the Ad Kit iOS SDK using Cocoapods:

1pod install SAKSDK

Step 3: Initialize the SDK

First, call the startWithConfiguration method on the SAKMobileAd shared instance, which will initialize the SDK. Once initialization is complete, it calls back a completion handler. You should call startWithConfiguration as early as possible and ideally at app launch. You only need to do this once.

3.1 Configure your Info.plist

Add the following items to your Info.plist:

  • Under NSAppTransportSecurity, add the NSAllowsArbitraryLoads key as a boolean and set it to YES.
  • Whitelist 424m5254lk.skadnetwork (Snap Ad Network Id). See the Apple Documentation for further instructions.
3.2 Create a SAKRegisterRequestConfigurationBuilder Object

Create an instance of SAKRegisterRequestConfigurationBuilder, which allows you to configure targeting and other parameters:

1SAKRegisterRequestConfigurationBuilder *configurationBuilder = [SAKRegisterRequestConfigurationBuilder new];
2[configurationBuilder withGender:SAKConfigurationGenderTypeFemale];
3[configurationBuilder withAge:18];
4[configurationBuilder withKeywords:@[ @"Game of Thrones", @"Snapchat", @"Football" ]];
5[configurationBuilder withSlcCategories:@[ @(SAK_SLC_AUTOMOTIVE_ENTHUSIASTS), @(SAK_SLC_ADVENTURE_SEEKERS)]];
3.3 Call SAKMobileAd to Initialize the SDK

This initializes the SDK, call this as early as possible in your code.

1[[SAKMobileAd shared] startWithConfiguration:[configurationBuilder build]
2completion:^(BOOL success, NSError *_Nullable error) {
3  if (error) {
4    if (error.code == SAKErrorNetworkError) {
5        // log something
6    } else if (error.code == SAKErrorNotEligible) {
7        // log something
8    } else if (error.code == SAKErrorFailedToParse) {
9        // log something
10    }
11  }
12}];

Step 4: Configure Ad Request (Optional)

When you want to present an ad to the user, create an SAKInterstitial container and call loadRequest, optionally providing additional configuration using SAKAdRequestConfigurationBuilder.

1SAKAdRequestConfigurationBuilder *configurationBuilder = [SAKAdRequestConfigurationBuilder new];
2[configurationBuilder withPublisherSlotId:@"01aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"];
3
4SAKAdRequestLocationConfiguration *locationConfiguration =
5    [[SAKAdRequestLocationConfiguration alloc] initWithLatitude:101
6                                                     longtitude:181
7                                               accuracyInMeters:4
8                              locationCapturedTimestampInMillis:32789798];
9[configurationBuilder withLocation:locationConfiguration];

Step 5: Load the Ad

If you’d like to display a full screen interstitial ad, create an SAKInterstitial container and call loadRequest, optionally providing additional configuration using SAKAdRequestConfigurationBuilder (see Step 4):

1// load ad request
2_interstitial = [[SAKInterstitial alloc] init];
3[_interstitial loadRequest:[configurationBuilder build]];

If you’d like to display a full screen rewarded ad, create an SAKRewardedAd container and call loadRequest, optionally providing additional configuration using SAKAdRequestConfigurationBuilder (see Step 4):

1// load ad request
2_rewardedAd = [[SAKRewardedAd alloc] init];
3[_rewardedAd loadRequest:[configurationBuilder build]];

If you’d like to display a banner or a medium rectangular ad, create an instance of SAKAdView and call loadRequest, optionally providing additional configuration using SAKAdRequestConfigurationBuilder (see Step 4):

1// load ad request
2_adView = [[SAKAdView alloc] initWithFormat:SAKAdViewFormatBanner];
3[_adView loadRequest:[configurationBuilder build]];

Step 6: Show the Ad Once it Has Loaded

For Interstitial Ads

To see all the events on the interstitial ad, set the delegate property on SAKInterstitial to an object that implements the SAKInterstitialDelegate protocol. The delegate property can be set to self as follows (mostly, the class that implements interstitial ads also acts as the delegate class):

1// load interstitial container
2if (!_interstitial) {
3    _interstitial = [SAKInterstitial new];
4    _interstitial.delegate = self;
5}

Now, you can access all the delegate methods to track different events on the interstitial:

MethodDescription
interstitialDidLoadAd loaded
didFailWithErrorRequest for the ad failed with an error
interstitialDidExpireAd was received, but it expired because it was never shown to the user
interstitialWillAppearAd will start appearing
interstitialDidAppearAd appeared
interstitialWillDisappearAd will start disappearing
interstitialDidDisappearAd disappeared
interstitialDidTrackImpressionAd impression was successfully tracked

The interstitialDidLoad method is called when the ad is fully loaded; so, you can show the ad inside that method using presentFromRootViewController as follows:

1// once the ad loads, show the ad
2- (void)interstitialDidLoad:(SAKInterstitial *)ad
3{
4  [_interstitial presentFromRootViewController:self // Controller that is presenting the interstitial
5                             dismissTransition:_transitionLocation]; // Frame (in screen coordinates) of the rectangle from which the interstitial transition begins and to which it returns.
6}

For Rewarded Ads

To see all the events on the rewarded ad, set the delegate property on SAKRewardedAd to an object that implements the SAKRewardedAdDelegate protocol. The delegate property can be set to self as follows (mostly, the class that implements rewarded ads also acts as the delegate class):

1// load rewarded ad container
2if (!_rewardedAd) {
3    _rewardedAd = [SAKRewardedAd new];
4    _rewardedAd.delegate = self;
5}

Now you can access all the delegate methods to track different events on the rewarded ad:

MethodDescription
rewardedAdDidLoadAd loaded
didFailWithErrorRequest for the ad failed with an error
rewardedAdDidExpireAd was received, but it expired because it was never shown to the user
rewardedAdWillAppearAd will start appearing
rewardedAdDidAppearAd appeared
rewardedAdWillDisappearAd will start disappearing
rewardedAdDidDisappearAd disappeared
rewardedAdDidEarnRewardUser has earned the reward

The rewardedAdDidLoad method is called when the ad is fully loaded; so, you can show the ad inside that method using presentFromRootViewController as follows:

1// once the ad loads, show the ad
2- (void)rewardedAdDidLoad:(SAKRewardedAd *)ad
3{
4  [ad presentFromRootViewController:self // Controller that is presenting the rewarded ad
5                  dismissTransition:_transitionLocation]; // Frame (in screen coordinates) of the rectangle from which
6                                                          // the ad transition begins and to which it returns.
7}

For Banners or Medium Rectangular Ads

Since SAKAdView is a UIView subclass, you can add it to your container view directly. If you need to handle delegate callbacks, you need to set delegate property to a class that implements SAKAdViewDelegate. The delegate property can be set to self as follows (mostly, the class that implements banner ads also acts as the delegate class):

1// Initialize ad view
2if (!_adView) {
3    _adView = [[SAKAdView alloc] initWithFormat:SAKAdViewFormatBanner];
4    _adView.delegate = self;
5    [self.view addSubview:_adView];
6}

Now you can access all the delegate methods to track different events on the ad view:

MethodDescription
adViewDidLoadAd loaded
didFailWithErrorThe request for the ad failed with an error
adViewDidClickUser has tapped the ad view
adViewDidTrackImpressionThe impression on the ad was successfully tracked

Step 7: Handle Ad Events

You can use the other delegate methods to take different actions based on the events that happen on the interstitial. Here, we show the ad once it loads (as seen in the previous step) and print messages on the console for every other event:

1- (void)interstitialDidLoad:(SAKInterstitial *)ad
2{
3  [_interstitial presentFromRootViewController:self
4      dismissTransition:_transitionLocation];
5}
6
7- (void)interstital:(SAKInterstitial *)ad didFailWithError:(NSError *)error
8{
9  print("didFailWithError")
10}
11
12- (void)interstitialDidExpire:(SAKInterstitial *)ad
13{
14  print("interstitialDidExpire")
15}
16
17- (void)interstitialWillAppear:(SAKInterstitial *)ad
18{
19  print("interstitialWillAppear")
20}
21
22- (void)interstitialDidAppear:(SAKInterstitial *)ad
23{
24  print("interstitialDidAppear")
25}
26
27- (void)interstitialWillDisappear:(SAKInterstitial *)ad
28{
29  print("interstitialWillDisappear")
30}
31
32- (void)interstitialDidDisappear:(SAKInterstitial *)ad
33{
34  print("interstitialDidDisappear")
35}
36
37- (void)interstitialDidTrackImpression:(SAKInterstitial *)ad
38{
39  print("interstitialDidTrackImpression")
40}