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.
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!");
}
}];
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!");
}
}];
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.
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:
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!");
}
}];
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];
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.
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.
Apps should handle errors that might happen when people share content. For more information on error handling, see Handling Errors
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}
.
Consult these documents for more information about using the iOS Share dialog in your app:
How Tos:
API Reference:
Samples:
FBDialogs
.FBDialogs
.