Installing sharekit

Step 0: Prerequisites

You'll need at least XCode 3.2.

Step 1: Get ShareKit files (add as submodule)

From the root of your project directory run this two commands

git submodule add -b development git://github.com/ShareKit/ShareKit.git Submodules/ShareKit
git commit -m 'ShareKit added as submodule'

This creates new submodule, downloads the files (currently development branch) to Submodules/ShareKit directory within your project and creates new commit with updated git repo settings.

Download includes ShareKit and an example project.

Step 2: Add ShareKit to your project

Add ShareKit files

Open new ShareKit folder in Finder. Drag Classes/ShareKit folder somewhere to your project navigator, preferably to the Submodules/ShareKit group. If you do not have Submodules group yet, it is fine to have one, so that you know that all submodules files are there.

Make sure the "Copy items into destination group's folder (if needed)" checkbox is checked.

Add Frameworks

Expand the 'Frameworks' group in your project's file list. Make sure you have the following frameworks:

• SystemConfiguration.framework
• Security.framework
• MessageUI.framework
• CFNetwork.framework

If you are missing any frameworks, right click the 'Frameworks' group and select Add -> Existing Frameworks. Select the framework you are missing and add it to your project.

Adding frameworks in Xcode 3

Base SDK and Deployment Targets

If you aren't already, you'll want to make sure your base SDK is set to Latest iOS. You can still support older versions (back to 3.*) by setting your deployment target.

Trim Cruft

Not everyone is interested in integrating with all of the services supported by ShareKit. To avoid bloating your app with unused code, browse in the Xcode navigation area to ShareKit/Sharers/Services/, select the folders you won't be needing, and simply delete them. (Edit->Delete, or right-click/control-click->Delete) ShareKit should still compile just fine, and the missing services will automatically disappear from the in-app list of sharing options.

Delete services you won't be using

Caution: Be careful if you delete the Actions of "Email" and/or "Text Message". There is code in the +[SHK initialize] method that swizzles the viewDidDisappear: on the system MFMailComposeViewController and MFMessageComposeViewController classes with custom SHK category methods defined in those Actions. If you delete them, and use ShareKit and then try to use a MFMailComposeViewController or MFMessageComposeViewController in your program, it will crash when they are dismissed. If you must remove those actions, make sure to comment out the swizzling code in +[SHK initialize].

Step 3: Configuration

See the Configuration page.

Step 4: Calling ShareKit

Import the ShareKit Header

In any class where you call ShareKit, you'll need to include the ShareKit header at the top. At the top of your class you'll probably see other imports already. Add ShareKit to the list:

#import "SHK.h"

Add a Share Button

This section is subjective and entirely depends on how you design your app. It assumes you know how to create a button that performs an action. If you'd like more guidance, take a look a the example project (included in the ShareKit download). It has a separate example for sharing links, images, text, and files.

You need to add a way to allow the user to say 'hey, I want to share this!'. It is up to you where to place this button and even what it looks like. If your app has a UIToolbar or UINavigationBar, a common practice is adding a UIBarButtonItem with the UIBarButtonSystemItemAction system item style. This icon has become the standard for sharing amongst iOS apps.

An example may look like:

[[UIBarButtonItem alloc]
 initWithBarButtonSystemItem:UIBarButtonSystemItemAction
 target:self
 action:@selector(share)]

Handling the Button Action

After you've added a button and set a target action to call when it's pushed, it's finally time to call ShareKit.

A user's entry point into ShareKit is an actionsheet. This actionsheet displays the user's most used services and a more button for additional options.

The actionsheet will only display services that can respond to the item you want to share. So the first step is to create an object (SHKItem) that describes what you want to share (a url, image, text, or file). With that item, you create an actionsheet and display it to the user. Here are the 3 steps together. In this example we'll share a URL:

- (void)myButtonHandlerAction
{
  // Create the item to share (in this example, a url)
  NSURL *url = [NSURL URLWithString:@"http://getsharekit.com"];
  SHKItem *item = [SHKItem URL:url title:@"ShareKit is Awesome!"];

  // Get the ShareKit action sheet
  SHKActionSheet *actionSheet = [SHKActionSheet actionSheetForItem:item];

  // Display the action sheet
  [actionSheet showFromToolbar:navigationController.toolbar];
}

That's it! ShareKit will take over from there and handle everything else. This includes logging the user in to their selected service, allowing them to edit the share item, displaying activity indicators, and even sharing offline.

Note: How/Where you display the action sheet is up to you. On an iPad you may want to display this as a popover from your share button. For all possible options, take a look at the UIActionSheet documentation.

To see examples sharing other types of content (images, text, or files) see additional documentation at getsharekit.com or the example project included in the ShareKit download.

Step 5: Offline Sharing

If your app can be used without an internet connection, you should support offline sharing. Luckily, this means only adding one additional line of code.

Most ShareKit services support offline sharing. This means when a user shares something while they are disconnected, ShareKit will store it and wait to send until they are connected again.

You just need to tell ShareKit when to retry these offline items. A good time to do this is when the app is opened. Simply add this line when you want ShareKit to try resending the items:

[SHK flushOfflineQueue];

Step 6: Implement Single Sign On (SSO) for Facebook

For SSO to work you must implement some methods in your app's AppDelegate.m file. First add headers

#import "SHKConfiguration.h"
#import "SHKFacebook.h"

and then add these methods

- (BOOL)handleOpenURL:(NSURL*)url
{
  NSString* scheme = [url scheme];
  NSString* prefix = [NSString stringWithFormat:@"fb%@", SHKCONFIG(facebookAppId)];
  if ([scheme hasPrefix:prefix])
  return [SHKFacebook handleOpenURL:url];
  return YES;
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation 
{
  return [self handleOpenURL:url];
}

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url 
{
  return [self handleOpenURL:url];  
}

Finally, add the custom URL scheme to the file MyiPhoneApp-Info.plist, for the key "URL types" (don't forget to replace [AppId] by your actual app id):

+ URL types
	+ Item 0   —   Dictionary
		+ URL identifier   —    String ""
		+ URL Schemes   —    Array
			+ Item 0   —   fb[AppId]