Sharing to Stories for Android Developers

As an Android developer, you can implement Sharing to Stories using implicit intents or our Android SDK.

Implicit Intents

To implement Sharing to Stories using implicit intents, in general, your sharing flow should:

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

You can pass the following content to the Facebook app:

ContentTypeDescription

Background asset *

Uri

Uri to an image (JPG, PNG) or video (H.264, H.265, WebM). Recommended image dimensions: device fullscreen or smaller. Videos can be 1080p and up to 20 seconds in duration. The Uri needs to be a content Uri to a local file on device.

Sticker asset *

Uri

Uri to an image (JPG, PNG). Recommended dimensions: 640x480. This image will be placed as a sticker over the background. The Uri needs to be a content Uri to a local file on device.

Background layer top color

String

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. Note that if you are passing a background asset, the asset will be used and these values will be ignored.

Background layer bottom color

String

A hex string color value used in conjunction with the background layer top 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. Note that if you are passing a background asset, the asset will be used and these values will be ignored.

Attribution Link

String

A deep link URL to content in your app. If missing, the Story will not include an attribution link. Facebook may read OG fields if available and generate a custom share type based on these. Use full URLs, including protocol (e.g. https://developers.facebok.com instead of developers.facebook.com).


This feature is currently in closed beta and only available to developers who have been approved for access.

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

Sharing A Background Asset

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

// Define photo or video asset URI and attribution link URL
Uri backgroundAssetUri = "your-background-asset-uri-goes-here";
String attributionLinkUrl = "your-deep-link-url-goes-here";
appId = your-facebook-app-id-goes-here;

// Instantiate implicit intent with ADD_TO_STORY action,
//background asset, and attribution link
Intent intent = new Intent("com.facebook.stories.ADD_TO_STORY");
intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG);
intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
intent.putExtra("com.facebook.platform.extra.APPLICATION_ID", appId);
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 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.

// Define photo or video asset URI and attribution link URL
Uri stickerAssetUri = FileProvider.getUriForFile(getContext(), FILE_PROVIDER, new File("share.jpg"));
String attributionLinkUrl = "your-deep-link-url-goes-here";
appId = your-facebook-app-id-goes-here;

// Instantiate implicit intent with ADD_TO_STORY action,
// sticker asset, background colors, and attribution link
Intent intent = new Intent("com.facebook.stories.ADD_TO_STORY");
intent.setType(MEDIA_TYPE_JPEG);
intent.putExtra("com.facebook.platform.extra.APPLICATION_ID", appId);
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.facebook.katana", stickerAssetUri, Intent.FLAG_GRANT_READ_URI_PERMISSION);
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

Android SDK

To implement Sharing to Stories using our Android SDK, in general, you should:

  • Model the content that will be shared — for images, construct a SharePhoto; for videos, construct a ShareVideo.
  • Add the modeled content to ShareStoryContent.

You can pass the following content to the Facebook app:

ContentTypeDescription

Background asset *

Uri

Uri to an image (JPG, PNG) or video (H.264, H.265, WebM). Recommended image dimensions: device fullscreen or smaller. Videos can be 1080p and up to 20 seconds in duration. The Uri needs to be a content Uri to a local file on device.

Sticker asset *

Uri

Uri to an image (JPG, PNG). Recommended dimensions: 640x480. This image will be placed as a sticker over the background. The Uri needs to be a content Uri to a local file on device.

Background color list *

List

A list of hex string color values used to generate a gradient from top to bottom, in the order in which they appear in the list. Note that if you are passing a background asset, the asset will be used and the color list will be ignored.

Attribution Link

String

A deep link URL to content in your app. If missing, the Story will not include an attribution link. Facebook may read OG fields if available and generate a custom share type based on these. Use full URLs, including protocol (e.g. https://developers.facebok.com instead of developers.facebook.com)


This feature is currently in closed beta and only available to developers who have been approved for access.

* You must pass the Facebook app a background asset, a sticker asset, or a list of background colors.

Sharing a Bitmap Image Background Asset

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

// Model an image background asset
Bitmap image = ...
SharePhoto photo = new SharePhoto.Builder()
        .setBitmap(image)
        .build();

// Define attribution link URL
String attributionLinkUrl = "your-deep-link-url";

// Add to ShareStoryContent
ShareStoryContent content = new ShareStoryContent.Builder()
        .setBackgroundAsset(photo)
        .setAttributionLink(attributionLinkUrl)
        .build();

Sharing an Image Background Asset with a URI

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

// Model an image background asset
Uri imageUri = "your-image-uri";
SharePhoto photo = new SharePhoto.Builder().setImageUrl(uri).build();

// Define attribution link URL
String attributionLinkUrl = "your-deep-link-url";

// Add to ShareStoryContent
ShareStoryContent content = new ShareStoryContent.Builder()
        .setBackgroundAsset(photo)
        .setAttributionLink(attributionLinkUrl)
        .build();

Sharing a Video Background Asset

This sample code shows how to pass the Facebook app a video background asset and an attribution link URL.

// Model a video background asset
Uri videoUri = "your-video-uri";
ShareVideo video  = new ShareVideo.Builder().setLocalUrl(videoUri).build();

// Define attribution link URL
String attributionLinkUrl = "your-deep-link-url";

// Add to ShareStoryContent
ShareStoryContent content = new ShareStoryContent.Builder()
        .setAttributionLink(attributionLinkUrl)
        .setBackgroundAsset(video)
        .build();

Sharing a Background Color

This sample code shows how to pass the Facebook app a image sticker asset, an attribution link URL, and a list of background colors to be rendered from top to bottom.

// Model an image sticker asset
Uri imageUri = "your-image-uri";
SharePhoto photo = new SharePhoto.Builder().setImageUrl(uri).build();

// Define attribution link URL
String attributionLinkUrl = "your-deep-link-url";

// Define color list
List<String> backgroundColorList = Arrays.asList("#33FF33", "#FF00FF", "#33FF33", "#FF00FF");

// Add to ShareStoryContent
ShareStoryContent content = new ShareStoryContent.Builder()
        .setStickerAsset(photo)
        .setAttributionLink(attributionLinkUrl)
        .setBackgroundColorList(backgroundColorList)
        .build();