Sharing on iOS

This guide details how to enable sharing from your iOS app to Facebook. When someone shares from your app, their content appears in their Timeline and in their friends' News Feeds.

People can also share content from your app to Facebook Messenger with Messenger Expression Platform or from Sharing's Message Dialog in iOS SDK.

Messenger SDK for iOSMessage Dialog

Prerequisites

Before you add sharing to your app you need to:

  • Add the Facebook SDK for iOS to your mobile development environment
  • Configure and link your Facebook app ID
  • Add your app id and display name to your app's .plist file.
  • Link the FBSDKShareKit.framework to your project.

Your app should not pre-fill any content to be shared. This is inconsistent with Facebook Platform Policy, see Facebook Platform Policy, 2.3.

iOS SDK Getting Started

Modeling Content

Versions 4.0+ of the Facebook SDKs have new models for sharing content. Each type of content has a interface you can use to represent it which conforms to <FBSDKSharingContent>. After you model the content, add a sharing interface to your app which conforms to <FBSDKSharing> such as FBSDKShareDialog.

When people share links from your app to Facebook, it includes attributes that show up in the post:

  • contentURL - the link to be shared
  • contentTitle - represents the title of the content in the link
  • imageURL - the URL of thumbnail image that appears on the post
  • contentDescription - of the content, usually 2-4 sentences

Build your share content for links with the FBSDKShareLinkContent model. For a list of all attributes, see FBSDKShareLinkContent reference.

Here's an example of how you can trigger the share:

FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:@"https://developers.facebook.com"];

Note: If your app share links to the iTunes or Google Play stores, we do not post any images or descriptions that you specify in the share. Instead we post some app information we scrape from the app store directly with the Webcrawler. This may not include images. To preview a link share to iTunes or Google Play, enter your URL into the Sharing Debugger.

Photos

People can share photos from your app to Facebook with the Share Dialog or with a custom interface:

  • Photos must be less than 12MB in size
  • People need the native Facebook for iOS app installed, version 7.0 or higher

Build your share content for photos with the FBSDKSharePhotoContent model. For a list of all attributes, see FBSDKSharePhotoContent reference.

- (void)imagePickerController:(UIImagePickerController *)picker
didFinishPickingMediaWithInfo:(NSDictionary *)info
{
  UIImage *image = info[UIImagePickerControllerOriginalImage];

  FBSDKSharePhoto *photo = [[FBSDKSharePhoto alloc] init];
  photo.image = image;
  photo.userGenerated = YES;
  FBSDKSharePhotoContent *content = [[FBSDKSharePhotoContent alloc] init];
  content.photos = @[photo];
  ...
}

Videos

People using your app can share videos to Facebook with the Share dialog or with your own custom interface:

  • The videos must be less than 12MB in size.
  • People who share should have Facebook for iOS client installed, version 26.0 or higher.

Build your share content for videos with the FBSDKShareVideoContent model. For a list of all attributes, see FBSDKShareVideoContent reference.

- (void)imagePickerController:(UIImagePickerController *)picker
didFinishPickingMediaWithInfo:(NSDictionary *)info
{
  NSURL *videoURL = [info objectForKey:UIImagePickerControllerReferenceURL];

  FBSDKShareVideo *video = [[FBSDKShareVideo alloc] init];
  video.videoURL = videoURL;
  FBSDKShareVideoContent *content = [[FBSDKShareVideoContent alloc] init];
  content.video = video;
  ...
}

The video URL videoURL must be an asset URL. You can get a video asset URL e.g. from UIImagePickerController.

Multimedia

People using your app can share a combination of photos and videos to Facebook with the Share dialog. Note the following:

  • People need to have iOS version 7.0 or higher.
  • People who share should have Facebook for iOS client installed, version 52.0 or higher.
  • Each photo and video must be less than 12MB in size.
  • People can share a maximum of 30 videos and photos at a time.

Build your multimedia share content with the FBSDKShareMediaContent model. For a list of all attributes, see FBSDKShareMediaContent reference.

FBSDKSharePhoto *photo = [FBSDKSharePhoto photoWith...
FBSDKShareVideo *video = [FBSDKShareVideo videoWith...
FBSDKShareMediaContent *content = [FBSDKShareMediaContent new];
content.media = @[photo, video];
}

Sharing Methods

After you handle content by building a model, you can either trigger the Share or Message dialogs or your own custom interface for sharing.

Buttons

On iOS, Facebook has native buttons to trigger shares.


Like Button

The Like button is a quick way for people to share content with their friends. A tap on the Like button will 'like' pieces of content from your app and share them on Facebook. To add a Like button to your view add the following code snippet to your view:

FBSDKLikeControl *button = [[FBSDKLikeControl alloc] init];
button.objectID = @"https://www.facebook.com/FacebookDevelopers";
[self.view addSubview:button];

Share Button

With the Share Button you will allow people to share content to their Facebook timeline, to a friend's timline or in a group. The Share button will call a Share dialog. To add a Share button to your view add the following code snippet to your view:

FBSDKShareButton *button = [[FBSDKShareButton alloc] init];
button.shareContent = content;  
[self.view addSubview:button];

Send Button

The Send button lets people privately send photos, videos and links to their friends and contacts using the Facebook Messenger. The Send button will call a Message dialog. To add a Send button to your view add the following code snippet to your view:

FBSDKSendButton *button = [[FBSDKSendButton alloc] init];
button.shareContent = content; 
[self.view addSubview:button];

If the Messenger app is not installed, the Send button will be hidden. Be sure that your app layout is appropriate when this button is hidden. To inspect whether the Send button can be displayed on the current device use the FBSDKSendButton property isHidden:

if (button.isHidden) {
  NSLog(@"Is hidden");
} else {
  [self.view addSubview:button];
}

Share Dialog

To use the Facebook-built sharing experiences, you want to define your content as in the modeling content section above, and then call the Share Dialog. For example, to share a link with the Share Dialog:


FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:@"http://developers.facebook.com"];
[FBSDKShareDialog showFromViewController:self
                              withContent:content
                                 delegate:nil];
                                 

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 SDK switches people to their default browser and opens the Feed Dialog. If someone wants to share an Open Graph story, the SDK opens the Web Share Dialog.

If the native Facebook app is installed, V4.0-V4.4 of the SDK will switch to the native Facebook for iOS app, then returns control to your app after a post is published. If you're using V4.5+ of the SDK, people will see the iOS Share Sheet instead of being switched to the native Facebook for iOS app, unless the share is an Open Graph story.

Message Dialog

The Message Dialog switches to the native Messenger for iOS app, then returns control to your app after a post is published.

[FBSDKMessageDialog showWithContent:content delegate:nil];

Note: Currently the message dialog is not supported on iPads.

iOS Integration

iOS 6+ includes a native share sheet that lets people post status updates, photos, videos and links to Facebook and includes support for setting the audience for the post and tagging the post with a location. You cannot share Open Graph Stories with the share sheet. The Facebook SDK supports the use of this native controller; beginning with V4.5 of the Facebook SDK, this experience is what people will see in most cases when you call the Facebook Share Dialog.

Use of the iOS share sheet is subject to Facebook Platform Policy, including section 2.3 which states that apps may not pre-fill in the context of the share sheet. This means apps may not pre-fill the share sheet's initialText field with content that wasn't entered by the user of the app.

This API also uses the same style block as other parts of the Facebook SDK. To show the native iOS share dialog, use:

// Example content. Replace with content from your app.
FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:@"https://developers.facebook.com"];

FBSDKShareDialog *dialog = [[FBSDKShareDialog alloc] init];
dialog.fromViewController = self;
dialog.content = content;
dialog.mode = FBSDKShareDialogModeShareSheet;
[dialog show];

Note that .fromViewController is required in order for the share sheet to present.

Additional Features

When you use the Facebook share dialog, you have additional options that aren't available when you share by using the API.

Hashtags

You can specify a single hashtag to appear with a shared photo, link, or video. This hashtag also appears in the Share dialog, and people have the the opportunity to remove it before publishing.

The following is an example of adding a hashtag to a link share.

FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:@"https://developers.facebook.com"];
content.hashtag = [FBSDKHashtag hashtagWithString:@"#MadeWithHackbook"];

Quote Sharing

You can enable people to highlight text to appear as a quote with a shared link. Alternatively, you can predefine a quote, for example, a pull quote in an article, to appear with the shared link. In either case, the quote appears in its own field separate from the user comments.

FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [@"https://developers.facebook.com/products/sharing"];
content.quote = @"Learn quick and simple ways for people to share content from your app or website to Facebook.";

Advanced Topics

With App Links you can link back to your app from Facebook posts published from your app.

When people click a Facebook post published from your app, it opens your app and you can even link to specific content within the app.

Custom Interface

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

Here's the Graph API call for posting a link to Facebook:

[FBSDKShareAPI shareWithContent:content delegate:nil];

Sharing Open Graph Stories

With Open Graph Stories people can share rich, structured content through a strongly typed API defined by Open Graph actions and objects.

Shared stories link back to your app or to your app's App Store page.

To learn more about how to add custom stories to your app, see Open Graph Stories in iOS.

Build your share content for Open Graph actions with the FBSDKShareOpenGraphContent model. For a list of all attributes, see FBSDKShareOpenGraphContent reference.

NSDictionary *properties = @{
  @"og:type": @"fitness.course",
  @"og:title": @"Sample Course",
  @"og:description": @"This is a sample course.",
  @"fitness:duration:value": @100,
  @"fitness:duration:units": @"s",
  @"fitness:distance:value": @12,
  @"fitness:distance:units": @"km",
  @"fitness:speed:value": @5,
  @"fitness:speed:units": @"m/s",
};
FBSDKShareOpenGraphObject *object = [FBSDKShareOpenGraphObject objectWithProperties:properties];
FBSDKShareOpenGraphAction *action = [[FBSDKShareOpenGraphAction alloc] init];
action.actionType = @"fitness.runs";
[action setObject:object forKey:@"fitness:course"];
FBSDKShareOpenGraphContent *content = [[FBSDKShareOpenGraphContent alloc] init];
content.action = action;
content.previewPropertyName = @"fitness:course";

iOS Simulator and Testing

If you are using Simulator to test sharing in your application, you will see errors if you try to share videos, Photos or Open Graph Actions. This is because you need Facebook for iOS installed which provides the Share Dialog. We do not support this for Simulator.

In the case of link shares, you do not need Facebook for iOS installed so this test case is possible. To test other Sharing scenarios, set up an actual test device with with Facebook for iOS installed.