Docs

Creative Kit iOS

Requirements


Getting Started

Add the following fields in your application’s Info.plist file.

Required:

  • SCSDKClientId (string): Your application’s client ID
  • LSApplicationQueriesSchemes (string-array): Must contain snapchat

Recommended:

  • SCSDKRedirectUrl (string): The URL Snapchat will redirect to if there’s an error
  • CFBundleURLSchemes (string-array): Must contain your redirect URL’s scheme — so if your redirect URL is my-app://abc/xy/z, this field must contain my-app. This is required if SCSDKRedirectURL is set

The Snap Kit SDK is initialized on application start-up by default. Auto-initialization can be disabled and the SDK can be manually initialized and de-initialized.

To disable Snap Kit auto-initialization, add the following entry to your app’s Info.plist file:

1<key>SnapKitAutoInit</key>
2<false/>

To manually initialize the Snap Kit SDK, call SCSDKSnapKit.initSDK().

To de-initialize the Snap Kit SDK, call SCSDKSnapKit.deinitialize().


Features

Preparing a Photo or Video to Send to Snapchat

Conditions

  • Images must be JPEG or PNG
  • Videos must be MP4 or MOV
  • Shared media must be 300 MB or smaller
  • Videos must be 60 seconds or shorter
  • All resource URLs should be local
  • Videos that are longer than 10 seconds are split up into multiple Snaps of 10 seconds or less

Let users send still photos from your app to Snapchat with the SCSDKPhotoSnapContent interface. For example, if someone wants to share game progress they can tap the Snapchat button in your app and you would set snapImage to the current game play screen’s PNG.

1// swift
2
3/* Main image content to be used in the Snap */
4let snapImage = /* Set your image here */
5let photo = SCSDKSnapPhoto(image: snapImage)
6let photoContent = SCSDKPhotoSnapContent(snapPhoto: photo)
1// objective-c
2
3/* Main image content to be used in Snap */
4UIImage *snapImage = /* Set your image here */;
5SCSDKSnapPhoto *photo = [[SCSDKSnapPhoto alloc] initWithImage:snapImage];
6SCSDKPhotoSnapContent *photoContent = [[SCSDKPhotoSnapContent alloc] initWithSnapPhoto:photo];

Alternately, you can set the photo using a URL:

1// swift
2
3let photo = SCSDKSnapPhoto(imageUrl: snapImageUrl)
1// objective-c
2
3SCSDKSnapPhoto *photo = [[SCSDKSnapPhoto alloc] initWithImageUrl:snapImageUrl];

To send a video, use SCSDKVideoSnapContent instead of SCSDKPhotoSnapContent. For example, if a user wants to send a clip of their game play to friends by tapping the Snap button, you would set the local URL to the video of user’s current game play:

1// swift
2
3/* Main image content to be used in Snap */
4let videoUrl = /* prepare a local video URL */
5let video = SCSDKSnapVideo(videoUrl: videoUrl)
6let videoContent = SCSDKVideoSnapContent(snapVideo: video)
1// objective-c
2
3/* Main image content to be used in Snap */
4NSURL *videoUrl = /* prepare a local video URL */;
5SCSDKSnapVideo *video = [[SCSDKSnapVideo alloc] initWithVideoUrl:videoUrl];
6SCSDKVideoSnapContent *videoContent = [[SCSDKVideoSnapContent alloc] initWithSnapVideo:video];

Now that you prepared the visuals in your app for users to Snap, learn how to enhance them in the next section.


Adding Captions, Stickers, or URL Attachments to Photos or Videos

You can choose to add a caption, sticker, or URL attachment to a set photo or video.

Conditions

  • Only one sticker is allowed
  • A still sticker must be a PNG or JPEG
  • An animated sticker must be a WebP (preferred) or GIF
  • Captions are limited to 250 characters
  • The attachment URL must be a properly formatted URL in string format
  • Universal links are not supported

Try the following options for adding a sticker, caption, or URL attachment to a photo:

1// swift
2
3/* Sticker to be used in the Snap */
4let stickerImage = /* Prepare a sticker image */
5let sticker = SCSDKSnapSticker(stickerImage: stickerImage)
6/* Alternatively, use a URL instead */
7// let sticker = SCSDKSnapSticker(stickerUrl: stickerImageUrl, isAnimated: false)
8
9/* Modeling a Snap using SCSDKPhotoSnapContent */
10let snap = SCSDKPhotoSnapContent(snapPhoto: photo)
11snap.sticker = sticker /* Optional */
12snap.caption = "Snap on Snapchat!" /* Optional */
13snap.attachmentUrl = "https://www.snapchat.com" /* Optional */
1// objective-c
2
3/* Sticker to be used in the Snap */
4UIImage *stickerImage = /* Prepare a sticker image */;
5SCSDKSnapSticker *sticker = [[SCSDKSnapSticker alloc] initWithStickerImage:stickerImage];
6/* Alternatively, use a URL instead */
7// SCSDKSnapSticker *sticker = [[SCSDKSnapSticker alloc] initWithStickerUrl:stickerImageUrl isAnimated:NO];
8
9/* Modeling a Snap using SCSDKPhotoSnapContent */
10SCSDKPhotoSnapContent *snap = [[SCSDKPhotoSnapContent alloc] initWithSnapPhoto:photo];
11snap.sticker = sticker; /* Optional */
12snap.caption = @"Snap on Snapchat!"; /* Optional */
13snap.attachmentUrl = @"https://www.snapchat.com"; /* Optional */

Adding a sticker, caption, or URL attachment to a video is the same:

1// swift
2
3/* Stickers to be used in Snap */
4let stickerImage = /* prepare a sticker image */
5let sticker = SCSDKSnapSticker(stickerImage: stickerImage)
6/* Alternatively, use a URL instead */
7// let sticker = SCSDKSnapSticker(stickerUrl: stickerImageUrl, isAnimated: false)
8
9/* Modeling a Snap using SCSDKVideoSnapContent */
10let snap = SCSDKVideoSnapContent(snapVideo: video)
11snap.sticker = sticker /* Optional */
12snap.caption = "Snap on Snapchat!" /* Optional */
13snap.attachmentUrl = "https://www.snapchat.com" /* Optional */
1// objective-c
2
3/* Stickers to be used in Snap */
4UIImage *stickerImage = /* prepare a sticker image */;
5SCSDKSnapSticker *sticker = [[SCSDKSnapSticker alloc] initWithStickerImage:stickerImage];
6/* Alternatively, use a URL instead */
7// SCSDKSnapSticker *sticker = [[SCSDKSnapSticker alloc] initWithStickerUrl:stickerImageUrl isAnimated:NO];
8
9/* Modeling a Snap using SCSDKVideoSnapContent*/
10SCSDKVideoSnapContent *snap = [[SCSDKVideoSnapContent alloc] initWithSnapVideo:video];
11snap.sticker = sticker; /* Optional */
12snap.caption = @"Snap on Snapchat!"; /* Optional */
13snap.attachmentUrl = @"https://www.snapchat.com"; /* Optional */

By default, the sticker appears in the center of the screen. You can set a default position and size to suggest specific placement, but users can resize and move the sticker around.


Creating On Top Of Photos or Videos Taken in Snapchat

Another option is to send just a sticker, caption, or an attachment URL to Snapchat and let the user take the Snap they want using Snapchat’s camera.

In this case, when your user taps the Snapchat button, Snapchat launches the camera screen. Your users capture the moment they want with a pre-populated sticker, caption, or attachment URL from your app. To try this option, use the SCSDKNoSnapContent interface:

1// swift
2
3/* Stickers to be used in Snap */
4let stickerImage = /* Prepare a sticker image */
5let sticker = SCSDKSnapSticker(stickerImage: stickerImage)
6/* Alternatively, use a URL instead */
7// let sticker = SCSDKSnapSticker(stickerUrl: stickerImageUrl, isAnimated: false)
8
9/* Modeling a Snap using SCSDKNoSnapContent */
10let snap = SCSDKNoSnapContent()
11snap.sticker = sticker /* Optional */
12snap.caption = "Snap on Snapchat!" /* Optional */
13snap.attachmentUrl = "https://www.snapchat.com" /* Optional */
1// objective-c
2
3/* Stickers to be used in Snap */
4UIImage *stickerImage = /* Prepare a sticker image */;
5SCSDKSnapSticker *sticker = [[SCSDKSnapSticker alloc] initWithStickerImage:stickerImage];
6/* Alternatively, use a URL instead */
7// SCSDKSnapSticker *sticker = [[SCSDKSnapSticker alloc] initWithStickerUrl:stickerImageUrl isAnimated:NO];
8
9/* Modeling a Snap using SCSDKNoSnapContent*/
10SCSDKNoSnapContent *snap = [[SCSDKNoSnapContent alloc] init];
11snap.sticker = sticker; /* Optional */
12snap.caption = @"Snap on Snapchat!"; /* Optional */
13snap.attachmentUrl = @"https://www.snapchat.com"; /* Optional */

Sending Your Photo, Video, or Sticker to Snapchat

The final step is connecting to Snapchat. Use the SCSDKSnapAPI interface to let your users start sending their creations to Snapchat:

1// swift
2
3var snapAPI: SCSDKSnapAPI?
4
5override func viewDidLoad() {
6  super.viewDidLoad()
7
8  snapAPI = SCSDKSnapAPI()
9}
10
11func yourMethodWhereYouShareToSnapchatFromWithCompletion(completionHandler: (Bool, Error?) ->()) {
12  // This method makes a user of the global UIPasteboard, and calling the method without synchronization might cause
13  // UIPasteboard data to be overwritten, while being read from Snapchat. Either synchronize the method call yourself,
14  // or disable user interaction until the share is over.
15  view.isUserInteractionEnabled = false
16  snapAPI?.startSending(content) { [weak self] (error: Error?) in
17    self?.view.isUserInteractionEnabled = true
18
19    // Handle response
20  }
21}
1// objective-c
2
3@implementation YourVC
4{
5    // Make sure this reference does not get deallocated until share is complete.
6    SCSDKSnapAPI *_scSdkSnapApi;
7}
8
9...
10
11- (void)viewDidLoad {
12  [super viewDidLoad];
13
14  _scSdkSnapApi = [SCSDKSnapAPI new];
15}
16
17...
18
19- (void)yourMethodWhereYouShareToSnapchatFromWithCompletion:(void (^)(BOOL success, NSError *error))completion
20{
21    // This method makes a user of the global UIPasteboard, and calling the method without synchronization might cause
22    // UIPasteboard data to be overwritten, while being read from Snapchat. Either synchronize the method call yourself,
23    // or disable user interaction until the share is over.
24    [self.view setUserInteractionEnabled:NO];
25
26    typeof(self) __weak wSelf = self;
27    [_scSdkSnapApi startSendingContent:snap completionHandler:^(NSError *error) {
28        [wSelf.view setUserInteractionEnabled:YES];
29        /* Handle response */
30    }];
31}

Adding a Lens Attachment

You are able to add Lens attachments so that users will open Snapchat to specific Lenses! To enable sharing with Dynamic Lenses, you must first create and publish a Lens using Lens Studio. When you initiate a share, you will need to point to the Lens using SCSDKLensSnapContent. Dynamic fields can be populated using key-value pairs in SCSDKLensLaunchDataBuilder. You can choose to add captions or a URL attachment to a Lens, but stickers and background photos or videos are disabled in this flow. In addition, you may optionally include launch data with the Lens attachment, to add other attributes to the Lens, like hints, for example.

Conditions

  • Stickers are not allowed
  • Captions are limited to 250 characters
  • The attachment URL must be a properly formatted URL in string format
  • Universal links are not supported
  • Launch data can be added in key-value pairs. The key must be a string and the value can be an int, float, double, string, or an array of any one of those types

Try the following options for adding a Lens attachment:

1// swift
2/* Modeling a Snap using SCSDKLensSnapContent & initializing with the lensUUID of your Lens attachment */
3let snap = SCSDKLensSnapContent(lensUUID: "123e4567e89b12d3a456426614174000")
4snap.caption = "Snap on Snapchat!" /* Optional */
5snap.attachmentUrl = "https://www.snapchat.com" /* Optional */
6
7// Optionally you can add launch data
8// First initialize the launch data builder:
9let launchDataBuilder = SCSDKLensLaunchDataBuilder()
10
11// Then add the key value pairs of the launch data:
12launchDataBuilder.addNSStringKeyPair("hint", value: "lens_hint_raise_your_eyebrows")
13
14// Then initialize and set the launch data to the Lens snap content type using the builder
15snap.launchData = SCSDKLensLaunchData(builder: launchDataBuilder)
1// objective-c
2/* Modeling a Snap using SCSDKLensSnapContent */
3SCSDKLensSnapContent *snap = [[SCSDKLensSnapContent alloc] initWithLensUUID:@”123e4567e89b12d3a456426614174000”];
4snap.caption = @"Snap on Snapchat!"; /* Optional */
5snap.attachmentUrl = @"https://www.snapchat.com"; /* Optional */
6
7/* Optionally can add launch data */
8/* First initialize the launch data builder: */
9SCSDKLensLaunchDataBuilder *launchDataBuilder = [[SCSDKLensLaunchDataBuilder alloc] init];
10
11/* Then add the key value pair of the launch data: */
12[launchDataBuilder addNSStringKeyPair:@"hint" value:@"lens_hint_raise_your_eyebrows"];
13
14/* Then initialize and set the launch data to the Lens snap content type using the builder: */
15snap.launchData = [SCSDKLensLaunchData initWithBuilder:launchDataBuilder];

Posting to Spotlight

Creative Kit for Spotlight provides Spotlight Creators and Snapstars with the ability to share content, with optionally attached topics, from third-party applications to Spotlight using Creative Kit; this makes it easier for them to create and share new content from their favorite Apps to Spotlight.

Topics in Spotlight are useful for identification (i.e. for campaigns, challenges, trends, etc.) and content categorization (i.e. #comedy, #dogs, #sports, etc.). When these topics are set, they propagate to the Send-To page and show up in the Spotlight Story section:

The Creative Kit API allows for up to 3 topics to be set for each Snap that is shared to Spotlight. Topics should be used wisely to increase engagement. We highly recommend deterring from using App names as topics.

The example below shows how to add topics to SCSDKVideoSnapContent. Topics can also be added to SCSDKSnapLensContent and SCSDKSnapNoContent in the same manner:

1/* Swift */
2let snapContent = SCSDKVideoSnapContent(snapVideo: video)
3snapContent.topics = SCSDKContentTopics(topics: ["sports”, "goal"])
1/* Objective C */
2SCSDKVideoSnapContent *snapContent = [[SCSDKVideoSnapContent alloc] initWithSnapVideo:video];
3snapContent.topics = [[SCSDKContentTopics alloc]
4    initWithTopics:
5    @[@"sports”, @"goal"]];
App Page and App Context Card

Spotlight Snaps are aggregated by the topics, sounds, and lenses that are used to create each of those Snaps, and are added to their respective Pages. We will use this same process for Snaps that are posted to Spotlight from 3PAs using Creative Kit -- App Pages will automatically be created from these submissions and users will be able to select them to view other content posted to Spotlight from that App.

In addition, Spotlight Snaps from 3PAs will generate App Context Cards, to show the source of the shared content. Tapping on the Context Card will link to the App Page shown above. From here, Snapchatters can browse Snaps created through the respective App and can install the App from within Snapchat:

Requirements

The Creative Kit API allows for up to 3 topics to be added to each Snap. Each topic is a string with the following requirements:

  • Maximum of 100 characters
  • Characters cannot include:
    • Punctuation Characters (except “_”)
    • Whitespace or Newline Characters
    • Symbol Characters
  • This excluded character set is Unicode General Categories S*, Z*, P* and U+000A ~ U+000D, U+0085

The SDK API will raise an error if topics do not meet the requirements above.

Please refer to our reference documentation for more information.


Requesting Access

In order to utilize this feature, you will need to register your app and request for access in the Snap Kit Developer Portal.

Under the Creative Kit toggle, you will see a subsection for Spotlight. Make sure to fill out the appropriate details and submit your app for approval:

Your app will go through our normal review process. Please note that until your Attachment URL Domain is approved by our review team, you will not be able to use and test this integration.

Once approved, the approved app version can be set to Production and you can begin posting Creative Kit content to Spotlight!


That’s it! You just learned how to integrate the Snapchat experience into your app.


What’s Next