Open Graph Stories in iOS

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, they can go 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 iOS app
  • Add the Facebook SDK for iOS to your project
  • Add your Facebook app ID, display name, and url scheme to your app's .plist file

For more info on development environments and app IDs, see iOS - Getting Started.

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 for people using your app, you'll have to submit them for review.

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 iOS 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
NSDictionary *properties = @{
  @"og:type": @"books.book",
  @"og:title": @"A Game of Thrones",
  @"og:description": @"In the frozen wastes to the north of Winterfell, sinister and supernatural forces are mustering.",
  @"books:isbn": @"0-553-57340-3",
};
FBSDKShareOpenGraphObject *object = [FBSDKShareOpenGraphObject objectWithProperties:properties];

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

// Create an action
FBSDKShareOpenGraphAction *action = [[FBSDKShareOpenGraphAction alloc] init];
action.actionType = @"books.reads";
[action setObject:object forKey:@"books:book"];

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

// Create the content
FBSDKShareOpenGraphContent *content = [[FBSDKShareOpenGraphContent alloc] init];
content.action = action;
content.previewPropertyName = @"books:book";

All objects and action types in your code must be lowercase.

Show the Share Dialog

Present the Share dialog by using the showFromViewController:withContent:delegate: class method on FBSDKShareDialog or by building up an instance of it and calling show.

[FBSDKShareDialog showFromViewController:viewController
                             withContent:content
                                delegate:nil];

Built-In Share Fallbacks

In past versions of the SDK for iOS, 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.

Check if the Share dialog is available using canShow on instances. Content validation can be checked with validateWithError:.

FBSDKShareDialog *shareDialog = [[FBSDKShareDialog alloc] init];
shareDialog.fromViewController = viewController;
shareDialog.shareContent = content;
if (![shareDialog canShow]) {
  // update the app UI accordingly
}
NSError *error;
if (![shareDialog validateWithError:&error]) {
  // check the error for explanation of invalid content
}

Adding Images

You can also add an image to your Open Graph story. This can be:

  • A hosted image your app provides that's on the web somewhere or
  • A local image captured by the owner of the device.

In this example, people using your app can select an image from their image gallery using a UIImagePickerController.

To do this ask the person to choose an image from the image picker then:

  • Move the code that posts to Facebook to the imagePickerController:didFinishPickingMediaWithInfo: method, which will be called once the person has finished choosing an image.

  • Construct an FBSDKSharePhoto model to represent the image.

  • Add the photo to the Open Graph action. To do this, you will need to modify your code to look like this:

// When the person is done picking the image
- (void)imagePickerController:(UIImagePickerController *)picker didFinishPickingMediaWithInfo:(NSDictionary *)info
{
  // Construct an FBSDKSharePhoto
  FBSDKSharePhoto *photo = [[FBSDKSharePhoto alloc] init];
  photo.image = info[UIImagePickerControllerOriginalImage];
  // Optionally set user generated to YES only if this image was created by the user
  // You must get approval for this capability in your app's Open Graph configuration
  // photo.userGenerated = YES;

  // Create an object
  NSDictionary *properties = @{
    @"og:type": @"books.book",
    @"og:title": @"A Game of Thrones",
    @"og:description": @"In the frozen wastes to the north of Winterfell, sinister and supernatural forces are mustering.",
    @"books:isbn": @"0-553-57340-3",
  };
  FBSDKShareOpenGraphObject *object = [FBSDKShareOpenGraphObject objectWithProperties:properties];

  // Create an action
  FBSDKShareOpenGraphAction *action = [[FBSDKShareOpenGraphAction alloc] init];
  action.actionType = @"books.reads";
  [action setObject:object forKey:@"books:book"];

  // Add the photo to the action. Actions
  // can take an array of images.
  [action setArray:@[photo] forKey:@"image"];

  // Create the content
  FBSDKShareOpenGraphContent *content = [[FBSDKShareOpenGraphContent alloc] init];
  content.action = action;
  content.previewPropertyName = @"books:book";

  [FBSDKShareDialog showFromViewController:viewController
                               withContent:content
                                  delegate:nil];
}

You can do something similar to capture images directly from the camera. Also, you can attach multiple images to an action, each as an FBSDKSharePhoto in the image array.

SDK Image size limits are 480x480px minimum resolution to 12MB maximum file size. The error code for images that go below or above the size limits is 102.

Additional Capabilities

Additional capabilities required App Review and approval before people can publish using them. Read about the guidelines for approval in this doc on the Submission Process.

You can tag places and people like this:

// Tag one or multiple people using their ids
content.peopleIDs = @[PEOPLE_IDS];

// Tag a place using the place's id
content.placeID = @"141887372509674"; // Facebook Seattle

Advanced Topics

Custom Interface

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

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

[FBSDKShareAPI shareWithContent:content delegate:nil];

If you run this code inside your app, you can check out the resulting object using the object browser. Remember that this is owned by the person that created it so in order to see your object you will need to choose the person's name in ''Object Owner'' on the top menu for the object to display:

A powerful feature of sharing Open Graph stories from your app is that you can use App Links to direct people to your native app when they interact with the story in News Feed.

You can learn more about implementing deep linking by reading our App Links for iOS guide.

Complex Open Graph Objects

Creating complex open graph objects that include inherited properties, or arrays of values should be delimited by colons or indexing notation instead of nesting objects in the JSON dictionary. That is, the JSON dictionary containing the open graph properties should be flat.

For example, if you have an open graph type with a property called 'checkpoints' that is an array of GeoPoints, you might use the following properties dictionary to pass to your FBSDKShareOpenGraphObject initialiation:

@"og:type": @"app-namespace:tour",
@"og:title": @"Example tour",
@"og:description": @"Some description lorem ipsum dolor",
@"app-namespace:start_point:latitude": @(48.85831),
@"app-namespace:start_point:longitude": @(2.29465),
@"app-namespace:end_point:latitude": @(45.85831),
@"app-namespace:end_point:longitude": @(2.29465),
@"app-namespace:checkpoints[0]:latitude": @(48.85831),
@"app-namespace:checkpoints[0]:longitude": @(2.29465),
@"app-namespace:checkpoints[1]:latitude": @(47.85831),
@"app-namespace:checkpoints[1]:longitude": @(2.29465),
@"app-namespace:distance": @(20)