Open Graph Stories in Android

With Open Graph people can share stories from your app to Facebook through a structured, strongly typed API.

When people engage with these stories they can go to your app or if they don't have your app installed, to your app's App Store page. This drives engagement and distribution for your app.

There are two ways to publish an Open Graph story:

Prerequisites

Before your app can publish Open Graph stories you'll need to:

  • Get a Facebook App ID, properly configured and linked to your Android app
  • Add the Facebook SDK for Android to your project
  • Add your Facebook app ID, display name, and url scheme to your app's manifest.html file

For more info on development environments and app IDs, see Getting Started Android SDK.

Creating Open Graph Stories

Open Graph stories are made up of a verb, or action and noun, known as object. To create a story, you need to define the action and object for your app's content.

The action and object can be one of several pre-built ones provided by Facebook, or for more advanced use cases, you can define your own.

Actions

See Using Actions for a list of actions available to you and learn how to publish them.

Objects

Objects are defined by adding Open Graph Markup on the web page where your content is hosted. You can see all the pre-defined objects Facebook offers in our Open Graph reference section.

App Review

Before you can publish stories on behalf of people, you'll have to submit them for review. In order to submit, first publish a test story.

Publish with Share Dialog

The Share dialog lets people publish stories from your app without Facebook Login or the publish_actions permission.

The Share dialog does this with a fast app-switch to the native Facebook for Android app installed in the device. Once a story is published, control returns to your app.

Here's an example of a story about "reading a book":

Creat an object with the object type books.book and set the properties on that object.

// Create an object
ShareOpenGraphObject object = new ShareOpenGraphObject.Builder()
    .putString("og:type", "books.book")
    .putString("og:title", "A Game of Thrones")
    .putString("og:description", "In the frozen wastes to the north of Winterfell, sinister and supernatural forces are mustering.")
    .putString("books:isbn", "0-553-57340-3")
    .build();

Then create an action and link the object to the action.

// Create an action
ShareOpenGraphAction action = new ShareOpenGraphAction.Builder()
    .setActionType("books.reads")
    .putObject("book", object)
    .build();

Finally, create the content model to represent the Open Graph story.

// Create the content
ShareOpenGraphContent content = new ShareOpenGraphContent.Builder()
    .setPreviewPropertyName("book")
    .setAction(action)
    .build();

All objects and action types in your code must be lowercase. All property names require namespaces.

Show the Share Dialog

Present the Share dialog by using the show method on ShareDialog.

ShareDialog.show(activityOrFragment, content);

Built-In Share Fallbacks

In past versions of the SDK for Android, your app had to check for a native, installed Facebook app before it could open the Share Dialog. If the person didn't have the app installed, you had to provide your own code to call a fallback dialog.

Now the SDK automatically checks for the native Facebook app. If it isn't installed the Web Share dialog launches as a fallback.

Adding Images

Apps can always attach images that are web accessible using URLs. This section explains how to attach photos from the device. Before you can attach images on the device, apps must configure a ContentProvider from the SDK in the AndroidManifest.xml. Remember to substitute your {Facebook-app-id} in the XML snippet below:

<provider android:authorities="com.facebook.app.FacebookContentProvider{Facebook-app-id}"
          android:name="com.facebook.FacebookContentProvider"
          android:exported="true" />

Attach Images to Actions

To attach pictures of a book to the books.reads action, an app should load images as a Bitmap and pass those to the Share dialog when it's opened. Example:

SharePhoto photo = new SharePhoto.Builder()
    .setBitmap(bitmap)
    .setUserGenerated(true)
    .build();

// Create an action
ShareOpenGraphAction action = new ShareOpenGraphAction.Builder()
    .setActionType("books.reads")
    .putObject("book", object)
    .putPhoto("image", photo)
    .build();

The Share dialog shows a preview of the story and use Bitmap passed above in the story preview instead of using the object's image.

If people took pictures with a camera, the app can ask to enable the User Generated Photos under the action type in the App Dashboard.

With this flag set to true the story displays as an intentional photo share on News Feed and Timeline. If this flag is false, the default Open Graph story with a small image appears in News Feed and Timeline.

Additional Capabilities

Make sure that you use these capabilities in a way that conforms to the submission guidelines.

You can tag places and people like this:

// Tag one or multiple people using their ids
List peopleIds = ...;
builder.setPeopleIds(peopleIds);

// Tag a place using the place's id
builder.setPlaceIds(placeId);

Advanced Topics

Troubleshooting:

Test Share Dialog on Android Emulator

Yes - a .apk of the Facebook app is included in the SDK download package. To install it, run:

~~~ $> adb install ~/facebook-android-sdk-3.5/bin/FBAndroid-{version}.apk


#### Share Dialog Fails Attaching Images {#troubleshooting_images}

If you're marking images as `user_generated`, make sure:
+ make sure images are at least 480 pixels in both dimensions
+ images from he app are loaded from the `drawable/` directory.  Loading them from the resolution-specific sub-directories can cause Android to downsize them below the 480x480 minimum size.

### Custom Interface {#custom}

To use your own interface for sharing, you need to:

* Build a custom interface that posts to the Graph API endpoint `/me/feed`
* Add [Facebook Login](/docs/facebook-login/android/) to your app
* Request [`publish_actions` permission](/docs/facebook-login/permissions/#reference-publish_actions)

Here's the Graph API call your app makes to posting a link to Facebook:

ShareApi.share(activity, content, null); ~~~

When you run this code in your app, view the result object with the Object Browser.

Remember that the person that created the object owns it so to see the object object, choose the person's name in ''Object Owner'' on the top menu: