8 captures
22 May 2013 - 01 Sep 2019
About this capture
Log In
Using the Share Dialog
Facebook iOS SDKUsing the Share Dialog
To get started using the Share dialog on iOS, you need to download the Facebook SDK for iOS 3.5+. Then use the techniques described here.
The Share Dialog lets you build great, native sharing experiences for people using your app. It works by making a one-line call to the SDK that configures the content to share, does an app switch to the Facebook app, and returns to the app once people have shared. Making the simplest use of the Share Dialog, people post a link. Here's what the code looks like:
NSURL* url = [NSURL URLWithString:@"https://developers.facebook.com/"]; [FBDialogs presentShareDialogWithLink:url handler:^(FBAppCall *call, NSDictionary *results, NSError *error) { if(error) { NSLog(@"Error: %@", error.description); } else { NSLog(@"Success!"); } }];
And here's what the dialog itself looks like:

The Share dialog supports status updates, link shares and publishing Open Graph actions. Each type of sharing lets people tag friends and places and choose an audience. When people are logged into Facebook in the app, the app can include friend and place tags.
Update a status
Here's the code you use to enable people using your app to update status:
[FBDialogs presentShareDialogWithLink:url handler:^(FBAppCall *call, NSDictionary *results, NSError *error) { if(error) { NSLog(@"Error: %@", error.description); } else { NSLog(@"Success!"); } }];
Share a link
Here's the code for sharing a link from your app:
NSURL* url = [NSURL URLWithString:@"https://developers.facebook.com/ios"]; [FBDialogs presentShareDialogWithLink:url handler:^(FBAppCall *call, NSDictionary *results, NSError *error) { if(error) { NSLog(@"Error: %@", error.description); } else { NSLog(@"Success!"); } }];
Publish Open Graph actions
Open Graph is a great way for apps to share rich stories through structured content. Open Graph actions help people tell richer stories by giving apps more control over the story being told as the language used to express the story in the News Feed. Using the iOS Share dialog makes that easier than ever for people: The Share dialog lets apps publish Open Graph actions without using Facebook Login and without having to people for a publish permission publish_actions​.
Here are a few examples of how apps can use built-in or custom action types and share those actions using the SDK.
There are two types of Open Graph objects: app-owned and user-owned. App-owned objects are a good fit where all of the people using an app share the same objects. For example, all people using Spotify share the song/album/artist catalog. User-owned objects are a good fit for apps where people create and own the app's content, for example, photo or note sharing apps.
Apps can use the Share dialog to publish actions that point to either type of object.
Publishing actions on app-owned objects
Say a book-reading app lets people share stories like "Eddie read a book." To do that, the app has an app-owned book library and uses <meta> tags to create books. The app shares stories about book reading using the following:
id<FBOpenGraphAction> action = (id<FBOpenGraphAction>)[FBGraphObject graphObject]; [action setObject:@"https://example.com/book/Snow-Crash.html" forKey:@"book"]; [FBDialogs presentShareDialogWithOpenGraphAction:action actionType:@"books.reads" previewPropertyName:@"book" handler:^(FBAppCall *call, NSDictionary *results, NSError *error) { if(error) { NSLog(@"Error: %@", error.description); } else { NSLog(@"Success!"); } }];
This displays a Share dialog that looks like this:
Publishing actions on user-owned objects
A cooking app lets people share content about meals they've cooked, and everyone owns their own meal-related content. To enable this, the app creates a user-owned meal object at the time of the share and connects to people with a cook action to tell a story like "Eddie cooked a meal." The app shares this using:
NSDictionary* object = @{ @"fbsdk:create_object": @YES @"type": @"cooking-app:meal", @"title": @"Lamb Vindaloo", @"url": @"https://example.com/cooking-app/meal/Lamb-Vindaloo.html", @"image": @"https://example.com/cooking-app/images/Lamb-Vindaloo.png", @"description": @"Spicy curry of lamb and potatoes." }; [FBDialogs presentShareDialogWithOpenGraphAction:action actionType:@"cooking-app:cook" previewPropertyName:@"meal" handler:^(FBAppCall *call, NSDictionary *results, NSError *error) { if(error) { NSLog(@"Error: %@", error.description); } else { NSLog(@"Success!"); } }];
Setting friend and place tags
To tag friends on the action, use Facebook user IDs, like this:
[action setTags:@[@"{friend-user-id-1}", @"{friend-user-id-2}"]];
To tag a place, use a Facebook place ID. The SDK includes a Place Picker that apps can use to let people pick a place. Apps can also use the Places Search API to find places around the current location. To add the place to an action, use this:
id<FBGraphPlace> place = (id<FBGraphPlace>)[FBGraphObject graphObject]; [place setId:@"141887372509674"]; // Facebook Seattle [action setPlace:place];
Best practices and troubleshooting tips
Tip 1: What if people don't have the Facebook app installed?
The Share dialog can't be displayed if people don't have the Facebook app installed. Apps can detect this by calling [FBDialogs canPresentShareDialogWithParams:nil]; and may disable or hide a sharing button or fall back to the Feed dialog to share on the web. See the HelloFacebookSample included with the iOS SDK for an example.
The Feed dialog doesn't yet support all of the features of the Share dialog, so in some cases, fallback won't be possible.
Tip 2: How can I test native Share dialog on the iOS simulator?
Since the native Share dialog is part of Facebook's iOS app, it can't run on a simulator. Use a physical device to test the native Share dialog. We're looking at ways to make it possible to test the native Share dialog on the simulator.
Tip 3: What happens if something goes wrong?
Apps should handle errors that might happen when people share content. For more information on error handling, see Handling Errors
Tip 4: The dialog doesn't work; what am I doing wrong?
It's common to have configuration errors in the .plist. Make sure that the .plist includes rows for FacebookAppID and FacebookDisplayName and URL Type entry for fb{app-id}.
Additional resources
Consult these documents for more information about using the iOS Share dialog in your app:
How Tos:
API Reference:
  • HelloFacebookSample​: shows basic usage of the Facebook SDK, including FBDialogs.
  • RPSSample: game sample that includes Open Graph sharing, using FBDialogs.
Updated about an hour ago
Facebook © 2013 · English (US)
About​Advertising​Careers​Platform PoliciesPrivacy Policy
Social PluginsFacebook LoginOpen GraphFacebook APIsGamesPaymentsApp CenterPromote Your AppiOSAndroidJavaScriptPHPMore SDKsFacebook SDK for iOSUsing the Share DialogLoginProfile PictureFriend PickerPlace Picker