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:

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

Allow Listing Facebook's Custom URL Scheme

You need to add Facebook's custom URL scheme to the allow list 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.

- (void)shareBackgroundImage {
      [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])
                      appID:@"your-app-id"]];
}

- (void)backgroundImage:(NSData *)backgroundImage 
                  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 to pasteboard
        NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.backgroundImage" : backgroundImage,
                                       @"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 Video Asset

This sample code shows how to pass the Facebook app a background layer video asset.

- (void)shareBackgroundVideo {
    NSURL *const backgroundVideoURL = [[NSBundle bundleForClass:[self class]]URLForResource:@"backgroundVideo" withExtension:@"mp4"];
    NSData *const backgroundVideoData = [NSData dataWithContentsOfURL:backgroundVideoURL];

    [self backgroundVideo: backgroundVideoData
                    appID: @"your-app-id"];
}

- (void)backgroundVideo:(NSData *)backgroundVideo
                  appID:(NSString *)appID {

    NSURL *urlScheme = [NSURL URLWithString:@"facebook-stories://share"];
    if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {
        
        // Assign background video asset to pasteboard
        NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.backgroundVideo" : backgroundVideo,
                                       @"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, 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"
                   appID:@"your-app-id"];
}

- (void)stickerImage:(NSData *)stickerImage 
    backgroundTopColor:(NSString *)backgroundTopColor 
 backgroundBottomColor:(NSString *)backgroundBottomColor
                 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 to pasteboard
      NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.stickerImage" : stickerImage,
                                     @"com.facebook.sharedSticker.backgroundTopColor" : backgroundTopColor,
                                     @"com.facebook.sharedSticker.backgroundBottomColor" : backgroundBottomColor,
                                     @"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, and a sticker layer image asset.

- (void)shareBackgroundAndStickerImage {
  [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])
           stickerImage:UIImagePNGRepresentation([UIImage imageNamed:@"stickerImage"])
                  appID:@"your-app-id"];
}

- (void)backgroundImage:(NSData *)backgroundImage 
           stickerImage:(NSData *)stickerImage 
                  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 to pasteboard
      NSArray *pasteboardItems = @[@{@"com.facebook.sharedSticker.backgroundImage" : backgroundImage,
                                     @"com.facebook.sharedSticker.stickerImage" : stickerImage,
                                     @"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
  }
}