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.

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, display name, and human-readable reason for photo access 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 Developer Policies.

iOS SDK Getting Started

Modeling 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.

Links

When people share links from your app to Facebook it includes a contentURL with the link to be shared. 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 50MB 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
{
  FBSDKShareVideo *video = [[FBSDKShareVideo alloc] init];
  if (@available(iOS 11, *)) {
    video.videoAsset = [info objectForKey:UIImagePickerControllerPHAsset];
  } else {
    video.videoURL = [info objectForKey:UIImagePickerControllerReferenceURL];
  }
  FBSDKShareVideoContent *content = [[FBSDKShareVideoContent alloc] init];
  content.video = video;
  ...
}

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.
Photos must be less than 12MB and video must be less than 50MB in size.
People can share a maximum of 1 video plus up to 29 photos or 30 photos.

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.

Buttons

On iOS, Facebook has native buttons to trigger shares.

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 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.

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 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. 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 Developer Policies, 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

App Links

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.

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 or Photos. 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.