Profile Expression Kit

Profile Expression Kit iOS Documentation

Integrate with Facebook Profile Pictures and Videos for your iOS app.

Requirements: OS X, the Profile Expression Kit SDK, Xcode (Documentation / Download) and iOS 7 or higher.

1. Create Facebook App

2. App Settings

3. Add SDK

4. Configure Xcode

5. Uploading Profile Pictures and Video to Facebook

6. String Translations

7. Two Way Deeplinking

8. FAQ

1. Create a Facebook App

If your app is not yet registered with Facebook and has an app ID, you should create it. You can you share an app ID across platforms. More details available here

Create a New App

2. Configure Facebook App Settings for iOS

  1. Select Settings in App Dashboard.
  2. Click Add Platform and choose iOS.
  3. Then provide your Bundle Identifier in the Bundle ID field.
  4. Enable Single Sign On.
  5. Click Save Changes

iOS App Settings

Bundle Identifier in Xcode

3. Add the SDK to your Xcode Project

To add the SDK in Xcode:

  1. Open ~/Documents/FBProfileExpressionKit
  2. Drag the FBSDKProfileExpressionKit.framework to Frameworks in Project Navigator. Create a new group Frameworks if it does not exist.
  3. Choose Create groups for any added folders.
  4. Deselect Copy items into destination group's folder. This references the SDK where you installed it rather than copying the SDK into your app.
  5. Add /Users/{username}/Documents/FBExpressionKit to the project's Framework Search Paths in Xcode's Build Settings.

The SDK automatically loads its framework and resource dependencies.

Framework Import Settings

4. Configure Xcode Project

Now configure the .plist for your project:

  1. In Xcode right-click your .plist file and choose "Open As Source Code".
  2. Copy & Paste the XML snippet into the body of your file (<dict>...</dict>).
  3. Replace:
    • {your-app-id} with your Facebook App ID.
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fb{your-app-id}</string>
    </array>
  </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>fb-profile-expression-platform</string>
</array>
<key>FacebookAppID</key>
<string>{your-app-id}</string>

This will allow the Profile Expression Kit to properly identify installed Facebook apps to perform an app switch.

5. Uploading Profile Pictures and Video to Facebook

The SDK supports uploading both profile videos and pictures to Facebook. Media is created in your app and using the SDK this media gets shared into the Facebook app and opened from there.

First you'll need to import the framework into your file

@import FBSDKProfileExpressionKit;

Determining if Facebook is installed

To determine whether a version of Facebook is installed that supports profile video and picture uploads you can call the following method:

[FBSDKProfileExpressionSharer isProfileMediaUploadAvailable];

Uploading profile videos

The SDK supports uploading profile videos to Facebook in two ways. The profile video can be referenced either with a reference to the video in someone's camera roll, or as NSData.

Uploading a profile video from NSData

[FBSDKProfileExpressionSharer uploadProfileVideoFromData:videoData metadata:nil];

Uploading a profile video from camera roll

To upload from a persons camera roll we need a reference to the location in camera roll. The API supports uploading camera roll items using either the ALAssetsLibrary or PhotoKit frameworks:

[FBSDKProfileExpressionSharer uploadProfileVideoWithLocalIdentifier:localIdentifier metadata:nil];

For an ALAsset the localIdentifier is ALAsset.defaultRepresentation.url.absoluteString. For a PHAsset it is PHAsset.localIdentifier.

Uploading a profile video from an AVAsset

Theres no way to directly serialize and share an AVAsset object between apps, so if you're working with an AVAsset object you can write it to a temporary file, before uploading that as NSData:

AVAssetExportSession *exporter = [[AVAssetExportSession alloc] initWithAsset:asset presetName:AVAssetExportPresetHighestQuality];
exporter.outputURL = exportURL;
[exporter exportAsynchronouslyWithCompletionHandler:^{
    NSData *assetData = [NSData dataWithContentsOfURL:exportURL];
    [FBSDKProfileExpressionSharer uploadProfileVideoFromData:assetData metadata:nil];
}];

Regardless of the method you choose to upload a profile video, the API will always check if a version of Facebook installed that can handle the shared link. All versions staring with v49 released on 2/22/2016 have this capability. If someone doesn't have Facebook installed, or has an older version, they're prompted with an alert to download the latest version from the AppStore.

Upload video flow example

This demonstrates how the integration looks, linking from Boomerangs capture flow into the Facebook Profile Video upload flow

%FB(devsite:video { id: 10153492752873553, width: 303, height: 540, title: "Boomerang Upload Integration" })

Uploading profile pictures

The SDK supports uploading profile pictures in the same two ways. to Facebook in two ways. The profile picture can be referenced either with a reference to the photo object in someone's camera roll, or as NSData. In addition a you can call a method to upload a UIImage directly.

The method calls are much the same as video.

[FBSDKProfileExpressionSharer uploadProfilePictureFromData:videoData metadata:nil];
[FBSDKProfileExpressionSharer uploadProfilePictureWithLocalIdentifier:localIdentifier metadata:nil];

and

[FBSDKProfileExpressionSharer uploadProfilePictureFromUIImage:uiimage metadata:nil];

Note that all the upload methods have an optional metadata parameter. This is for sending additional information from your app to the Facebook app, but is currently unused and can safely be set to nil.

6. String Translations

There are a number of strings displayed to people who don't have Facbeook installed, prompting them to download it from the AppStore. The following strings will need to be translated in your app:

NSLocalizedString(@"Get Facebook", @"Alert title telling a user they need to install Facebook")
NSLocalizedString(@"You'll need to install the latest version of Facebook to share this.", @"Alert message when an old version of Facebook is installed")
NSLocalizedString(@"Not Now", @"Button label when user doesn't want to install Facebook")
NSLocalizedString(@"Install", @"Button label to install Facebook")
NSLocalizedString(@"Share", @"Button label for sharing content")

7. Two Way Deeplinking

In the future Facebook may link out to your app to encourage people to create cool content in your app. In order to support this behavior your app will need some additional configuration.

Configure you UIApplicationDelegate

Your app will have already been setup to respond to fb<yourappid>:// urls. The Facebook app will open your app this way. You'll need to add some additional code inside your app delegate to handle these incoming link requests

Inside your app delegates application:openURL:options: method you'll need to add the following code

[FBSDKProfileExpressionURLHandler parseURL:url];

Determining if your app has been launched from Facebook

At anytime you can call the following code to determine if your app was launched from Facebook by calling the following code:

[FBSDKProfileExpressionSharer wasLaunchedFromFacebook];

This will return YES so long as the app was launched from Facebook. It will automatically reset to NO if a user backgrounds your app.

When launched from Facebook your app should immediately open into whatever screen you have to produce videos or pictures. Once someone has finished creating a video or photo you should share the content to Facebook immediately, rather than displaying a screen displaying multiple share options. This will allow a seamless transition from Facebook to your app and back to Facebook.

8. FAQ

Why do I see a 'You'll need to install the latest version of Facebook to share this' message when trying to upload a Profile Video

The SDK uses a canOpenURL: call to check if a version of Facebook is installed that supports profile video sharing. If you are seeing this message even with Faebook installed, you may have forgotten to add the LSApplicationQueriesSchemes to your app's Info.plist.

Why do I see a '{app} wants to open Facebook' alert dialog when trying to upload a Profile Video to Facebook?

In iOS 9, the app switches can prompt people with a confirmation dialog.

Why do I see console messages like canOpenURL: failed for URL: "fb-profile-expression-platform://" or "This app is not allowed to query for scheme fb-profile-expression-platform".

This is an Xcode warning indicating the the canOpenURL: call returned false. As long as you have configured the LSApplicationQueriesSchemes entry in your plist as described above, you can ignore this warning