Installing sharekit

Step 0: Prerequisites

You'll need newest ios sdk (5.1) and run ShareKit on devices with iOS 4.x and newer.

Step 1: Get ShareKit files (as Git submodule)

Info for people, who do not use git yet: The process of getting ShareKit files is very simple and quick, if your project is a Git repo. If it is not, you can create one easily in terminal app entering git init in the root of your project directory. If you decide not to use git, you will have to download all ShareKit files + separately download each submodule, and put the files in corresponding subdirectory of ShareKit/Submodules.

In terminal navigate to the root of your project directory and run these commands (assuming your project is a git repo):

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

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

Now navigate to the newly created ShareKit dir and download all submodules files

cd Submodules/ShareKit
git submodule update --init --recursive

Thanks to the fact that you added ShareKit as submodule, it is easy to keep it updated to the newest version. For information on how to update, see FAQ.

Step 2: Add ShareKit to your project

Add ShareKit as xCode subproject

Open your app's project in Xcode. Make sure, that ShareKit project itself is NOT opened in xCode.

Drag the ShareKit project file (ShareKit.xcodeproj) from Finder into your project navigator in xCode.

Now make small adjustments in your project's app target:

1. add ShareKit's targets as depenedencies to your project's build phase: your project's app target - build phases - target dependencies add 2 new targets from ShareKit subproject: "Static Library" and "Resource Bundle"

2. add ShareKit's "libShareKit.a" to your project's Link Binary With Libraries build phase

3. add ShareKit's "Resource Bundle" to your project's Copy Bundle Resources build phase: expand shareKit subproject - expand products - move "ShareKit.bundle" to Copy Bundle Resources build phase in your project's target

4. change your project's app target build settings:

• User header search paths: set it RECURSIVELY to the directory where you put submodules in. If you followed our install wiki, it should be Submodules/ . Two asterisks are a sign, that you have checked Recursive option.

• Other Linker Flags: -ObjC -all_load

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 (for Flickr)
• CoreLocation.framework (for Foursquare)
• Twitter.framework (it is new in iOS 5, so if you deploy to older versions of iOS, mark it optional)
• CoreFoundation.framework (mark it optional, it is a workaround for issue #394)
• if you plan to use print sharer, and have deployment target < iOS 4.2 you have to mark UIKit.framework optional too, unfortunately.

If you are missing any frameworks, go to your app target - Build Phases - Link Binary With Libraries - add missing libraries by pressing small + in the left bottom corner of the Link Binary With Libraries section.

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 4.*) by setting your deployment target.

Step 3: Smoke Test

Build your project. If it won't build, try these troubleshooting steps.

Issue: "error: no such file or directory:"

You may not have the submodules installed correctly. Compare the contents of ShareKit/Submodules with the list in ShareKit/.gitmodules. If the submodules aren't installed, you may have to go back and very carefully follow the instructions in Step 1.

Issue: "'OAuthConsumer/OAToken.h' file not found" (or similar)

If, up until now, you have been using a library that is already part of ShareKit (e.g., SBJSON, facebook-ios-sdk, Twitter+OAuth, et. al), you may need to remove references to those libraries. Don't forget to double check your Framework, Header, Library, and User Header Search Paths and remove any older, still-lingering references as well. (In your project and/or target settings, under "Build Settings", search for "Search Paths".)

Step 4: Configuration

See the Configuration page.

Step 5: 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];

  // ShareKit detects top view controller (the one intended to present ShareKit UI) automatically,
  // but sometimes it may not find one. To be safe, set it explicitly
  [SHK setRootViewController:self];

  // 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 6: 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 7: 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]

Source code of your MyiPhoneApp-Info.plist should be look like this:

<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>fbYOUR_APP_ID</string>
		</array>
	</dict>
</array>