Sharing to Stories for iOS Developers

iOS implementations use a custom URL scheme to launch the Facebook app and pass it content. In general, your sharing flow should:

  1. Check that your app can resolve Facebook's custom URL scheme.
  2. Assign the content that you want to share to the pasteboard.
  3. Resolve the custom URL scheme if your app is able to.

Shareable Content

You can pass the following content to the Facebook app:

ContentKey NameTypeDescription

Facebook app ID *

com.facebook.sharedSticker.appID

NSString *

(Required) Your Facebook app ID. Add the ID to your app’s Info.plist file. This allows us to link back to your app after sharing content to Facebook. See Configure Info.plist for instructions.

Background image asset *

com.facebook.sharedSticker.backgroundImage

NSData *

Data for an image asset in a supported format (JPG, PNG). Recommended dimensions: device fullscreen or smaller.

Background video asset *

com.facebook.sharedSticker.backgroundVideo

NSData *

Data for video asset in a supported format (H.264, H.265, WebM). Videos can be 1080p and up to 20 seconds in duration. Under 50 MB recommended.

Sticker asset *

com.facebook.sharedSticker.stickerImage

NSData *

Data for an image asset in a supported format (JPG, PNG). Recommended dimensions: 640x480. This image will be placed as a sticker over the background.

Background layer top color

com.facebook.sharedSticker.backgroundTopColor

NSString *

A hex string color value used in conjunction with the background layer bottom color value. If both values are the same, the background layer will be a solid color. If they differ, they will be used to generate a gradient instead.

Background layer bottom color

com.facebook.sharedSticker.backgroundBottomColor

NSString *

A hex string color value used in conjunction with the background layer bottom color value. If both values are the same, the background layer will be a solid color. If they differ, they will be used to generate a gradient instead.

Attribution URL

com.facebook.sharedSticker.contentURL

NSString *

A deep link URL to content in your app. If missing, the story will not include an attribution link. This feature is currently in closed beta and only available to approved developers.

* In addition to your app's app ID, you must pass the Facebook app a background asset (image or video), a sticker asset, or both.

Whitelisting Facebook's Custom URL Scheme

You need to whitelist Facebook's custom URL scheme in order for your app use it. To do this, add facebook-stories:// to the LSApplicationQueriesSchemes key in your app's Info.plist.

Sharing a Background Asset

This sample code shows how to pass the Facebook app a background layer image asset and an attribution deep link.

- (void)shareBackgroundImage {
      [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])
             attributionURL:@"http://your-deep-link-url"
                      appID:@"your-app-id"]];
}

- (void)backgroundImage:(NSData *)backgroundImage 
         attributionURL:(NSString *)attributionURL
                  appID:(NSString *)appID {

  // Verify app can open custom URL scheme, open if able
  NSURL *urlScheme = [NSURL URLWithString:@"facebook-stories://share"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {
  
        // Assign background image asset and attribution link URL to pasteboard
        NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.backgroundImage" : backgroundImage,
                                       @"com.facebook.sharedSticker.contentURL" : attributionURL,
                                       @"com.facebook.sharedSticker.appID" : appID}];
        NSDictionary *pasteboardOptions = @{UIPasteboardOptionExpirationDate : [[NSDate date] dateByAddingTimeInterval:60 * 5]};
        // This call is iOS 10+, can use 'setItems' depending on what versions you support
        [[UIPasteboard generalPasteboard] setItems:pasteboardItems options:pasteboardOptions];
    
        [[UIApplication sharedApplication] openURL:urlScheme options:@{} completionHandler:nil];
  } else {
      // Handle older app versions or app not installed case
  }
}

Sharing a Sticker Asset

This sample code shows how to pass the Facebook app a sticker layer image asset, an attribution deep link, and a set of background layer colors. Note that if you do not supply background layer colors, we will set the background layer color to #222222.

- (void)shareStickerImage {
      [self stickerImage:UIImagePNGRepresentation([UIImage imageNamed:@"stickerImage"])
      backgroundTopColor:@"#444444"
   backgroundBottomColor:@"#333333"
          attributionURL:@"http://your-deep-link-url"
                   appID:@"your-app-id"];
}

- (void)stickerImage:(NSData *)stickerImage 
    backgroundTopColor:(NSString *)backgroundTopColor 
 backgroundBottomColor:(NSString *)backgroundBottomColor
        attributionURL:(NSString *)attributionURL
                 appID:(NSString *)appID {

  // Verify app can open custom URL scheme. If able,
  // assign assets to pasteboard, open scheme.
  NSURL *urlScheme = [NSURL URLWithString:@"facebook-stories://share"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {

  // Assign sticker image asset and attribution link URL to pasteboard
      NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.stickerImage" : stickerImage,
                                     @"com.facebook.sharedSticker.backgroundTopColor" : backgroundTopColor,
                                     @"com.facebook.sharedSticker.backgroundBottomColor" : backgroundBottomColor,
                                     @"com.instagram.sharedSticker.contentURL" : attributionURL,
                                     @"com.facebook.sharedSticker.appID" : appID}];
      NSDictionary *pasteboardOptions = @{UIPasteboardOptionExpirationDate : [[NSDate date] dateByAddingTimeInterval:60 * 5]};
      // This call is iOS 10+, can use 'setItems' depending on what versions you support
      [[UIPasteboard generalPasteboard] setItems:pasteboardItems options:pasteboardOptions];

      [[UIApplication sharedApplication] openURL:urlScheme options:@{} completionHandler:nil];
  } else {
      // Handle older app versions or app not installed case
  }
}

Sharing a Background Asset and Sticker Asset

This sample code shows how to pass the Facebook app a background layer image asset, a sticker layer image asset, and an attribution deep link URL.

- (void)shareBackgroundAndStickerImage {
  [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])
           stickerImage:UIImagePNGRepresentation([UIImage imageNamed:@"stickerImage"])
         attributionURL:@"http://your-deep-link-url"
                  appID:@"your-app-id"];
}

- (void)backgroundImage:(NSData *)backgroundImage 
           stickerImage:(NSData *)stickerImage 
         attributionURL:(NSString *)attributionURL
                  appID:(NSString *)appID {

  // Verify app can open custom URL scheme. If able,
  // assign assets to pasteboard, open scheme.
  NSURL *urlScheme = [NSURL URLWithString:@"facebook-stories://share"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {

      // Assign background and sticker image assets and 
      // attribution link URL to pasteboard
      NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.backgroundImage" : backgroundImage,
                                     @"com.facebook.sharedSticker.stickerImage" : stickerImage,
                                     @"com.facebook.sharedSticker.contentURL" : attributionURL,
                                     @"com.facebook.sharedSticker.appID" : appID}];
      NSDictionary *pasteboardOptions = @{UIPasteboardOptionExpirationDate : [[NSDate date] dateByAddingTimeInterval:60 * 5]};
      // This call is iOS 10+, can use 'setItems' depending on what versions you support
      [[UIPasteboard generalPasteboard] setItems:pasteboardItems options:pasteboardOptions];

      [[UIApplication sharedApplication] openURL:urlScheme options:@{} completionHandler:nil];
  } else {
      // Handle older app versions or app not installed case
  }
}