Sharing to Stories

With Sharing to Stories, you can allow your app's Users to share your content as an Instagram story.

Overview

By using Android Implicit Intents and iOS Custom URL Schemes, your app can pass photos, videos, and stickers to the Instagram app. The Instagram app will receive this content and load it in the story composer so the User can publish it to their Instagram Stories.

The Instagram app's story composer is comprised of a background layer and a sticker layer. Background Layer The background layer fills the screen and you can customize it with a photo, video, solid color, or color gradient. Sticker Layer The sticker layer can contain an image, and the layer can be further customized by the User within the story composer.

Android Developers

Android implementations use implicit intents to launch the Instagram app and pass it content. In general, your sharing flow should:

1. Instantiate an implicit intent with the content you want to pass to the Instagram app.
2. Start an activity and check that it can resolve the implicit intent.
3. Resolve the activity if it is able to.

Shareable Content

You can pass the following content to the Instagram app:

* You must pass the Instagram app a background asset, a sticker asset, or both.

Sharing a Background Asset

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

// Define image asset URI and attribution link URL
Uri backgroundAssetUri = Uri.parse("your-image-asset-uri-goes-here");
String attributionLinkUrl = "https://www.my-aweseome-app.com/p/BhzbIOUBval/";
String sourceApplication = "com.my.app";

// Instantiate implicit intent with ADD_TO_STORY action,
// background asset, and attribution link
Intent intent = new Intent("com.instagram.share.ADD_TO_STORY");
intent.putExtra("source_application", sourceApplication);

intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG);
intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
intent.putExtra("content_url", attributionLinkUrl);

// Instantiate activity and verify it will resolve implicit intent
Activity activity = getActivity();
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

Sharing a Sticker Asset

This sample code shows how to pass the Instagram 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.

// Define image asset URI and attribution link URL
Uri stickerAssetUri = Uri.parse("your-image-asset-uri-goes-here");
String attributionLinkUrl = "https://www.my-aweseome-app.com/p/BhzbIOUBval/";
String sourceApplication = "com.my.app";

// Instantiate implicit intent with ADD_TO_STORY action,
// sticker asset, background colors, and attribution link
Intent intent = new Intent("com.instagram.share.ADD_TO_STORY");
intent.putExtra("source_application", sourceApplication);

intent.setType(MEDIA_TYPE_JPEG);
intent.putExtra("interactive_asset_uri", stickerAssetUri);
intent.putExtra("content_url", attributionLinkUrl);
intent.putExtra("top_background_color", "#33FF33");
intent.putExtra("bottom_background_color", "#FF00FF");

// Instantiate activity and verify it will resolve implicit intent
Activity activity = getActivity();
activity.grantUriPermission(
    "com.instagram.android", stickerAssetUri, Intent.FLAG_GRANT_READ_URI_PERMISSION);
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

Sharing a Background Asset and a Sticker Asset

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

// Define background and sticker asset URIs and attribution link URL
Uri backgroundAssetUri = Uri.parse("your-background-image-asset-uri-goes-here");
Uri stickerAssetUri = Uri.parse("your-sticker-image-asset-uri-goes-here");
String attributionLinkUrl = "https://www.my-aweseome-app.com/p/BhzbIOUBval/";
String sourceApplication = "com.my.app";

// Instantiate implicit intent with ADD_TO_STORY action,
// background asset, sticker asset, and attribution link
Intent intent = new Intent("com.instagram.share.ADD_TO_STORY");
intent.putExtra("source_application", sourceApplication);

intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG);
intent.putExtra("interactive_asset_uri", stickerAssetUri);
intent.putExtra("content_url", attributionLinkUrl);

// Instantiate activity and verify it will resolve implicit intent
Activity activity = getActivity();
activity.grantUriPermission(
    "com.instagram.android", stickerAssetUri, Intent.FLAG_GRANT_READ_URI_PERMISSION);
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

iOS Developers

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

1. Check that your app can resolve Instagram'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 Instagram app:

* You must pass the Instagram app a background asset (image or video), a sticker asset, or both.

Whitelisting Instagram's Custom URL Scheme

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

Sharing a Background Asset

This sample code shows how to pass the Instagram 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"];
}

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

  // Verify app can open custom URL scheme, open if able
  NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share?source_application=com.my.app"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {
  
        // Assign background image asset and attribution link URL to pasteboard
        NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.backgroundImage" : backgroundImage,
                                       @"com.instagram.sharedSticker.contentURL" : attributionURL}];
        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 Instagram 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"];
}

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

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

  // Assign sticker image asset and attribution link URL to pasteboard
      NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.stickerImage" : stickerImage,
                                     @"com.instagram.sharedSticker.backgroundTopColor" : backgroundTopColor,
                                     @"com.instagram.sharedSticker.backgroundBottomColor" : backgroundBottomColor,
                                     @"com.instagram.sharedSticker.contentURL" : attributionURL}];
      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 Instagram 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"];
}

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

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

      // Assign background and sticker image assets and 
      // attribution link URL to pasteboard
      NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.backgroundImage" : backgroundImage,
                                     @"com.instagram.sharedSticker.stickerImage" : stickerImage,
                                     @"com.instagram.sharedSticker.contentURL" : attributionURL}];
      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 to Facebook Stories

You can also allow your app's Users to share your content as a Facebook story. To learn how to do this, please refer to our Facebook Sharing to Stories documentation.