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' 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 SharingContent. After you model the content, add a sharing interface to your app which conforms to Sharing or use the provided ShareDialog class.

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

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

guard let url = URL(string: "https://developers.facebook.com") else {
    // handle and return
}

let content = ShareLinkContent()
content.contentURL = url

let dialog = ShareDialog(
    viewController: self,
    content: content,
    delegate: self
)
dialog.show()

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

func imagePickerController(
    _ picker: UIImagePickerController, 
    didFinishPickingMediaWithInfo 
    info: [UIImagePickerController.InfoKey : Any]
) {
    guard let image = info[.originalImage] as? UIImage else {
        // handle and return
        return
    }
    let photo = SharePhoto(
        image: image,
        userGenerated: true
    )
    var content = SharePhotoContent()
    content.photos = [photo]
    // use the content
}

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.

func imagePickerController(
    _ picker: UIImagePickerController,
    didFinishPickingMediaWithInfo info: [UIImagePickerController.InfoKey : Any]
) {
    let video: ShareVideo

    if #available(iOS 11, *) {
        guard let videoAsset = info[.phAsset] as? PHAsset else {
            return
        }
        video = ShareVideo(videoAsset: videoAsset)
    } else {
        guard let url = info[.referenceURL] as? URL else {
            return
        }
        video = ShareVideo(videoURL: url)
    }
}

Multimedia

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

• People who share should have Facebook for iOS client installed.
• 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 ShareMediaContent model.

let photo = SharePhoto(...)
let video = ShareVideo(...)

var content = ShareMediaContent()
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 timeline 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:

var button = FBShareButton()
button.shareContent = content
// Add button to view

---

Send Button

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

var button = SendButton()
button.shareContent = content
// Add button to view

If the Messenger app is not installed, the Send button will be dimmed. To inspect whether the Send button can be used on the current device use the SendButton property isImplicitlyDisabled:

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:

guard let url = URL(string: "https://developers.facebook.com") else {
    // handle and return
}

let content = ShareLinkContent()
content.contentURL = url

let dialog = ShareDialog(
    viewController: self,
    content: content,
    delegate: self
)
dialog.show()

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

MessageDialog(content: content, delegate: delegate).show()

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; 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:

let dialog = ShareDialog(
    viewController: self,
    content: content,
    delegate: nil
)
dialog.mode = .shareSheet
dialog.show()

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

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.

let content = ShareLinkContent()
guard let url = URL(string: "https://developers.facebook.com") else { return }

content.contentURL = url
content.hashtag = Hashtag("#MadeWithHackbook")

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.