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:
- Using the Share dialog
- Using your own custom interface
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 modelto 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:
- Build a custom interface that posts to the Graph API endpoint
/me/feed - Add Facebook Login to your app
- Request
publish_actionspermission
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:

App Links
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)

