Installing sharekit
You'll need at least Xcode 3.2 and run ShareKit on devices with iOS 4.x and newer.
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 init
git submodule update
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.
Copy files from example project
Open both the example project (that you downloaded in step 1 above) and your app's project in XCode.
Drag the ShareKit Group from the example project into your project's Groups & Files.
Make sure the "Copy items into destination group's folder (if needed)" checkbox is UNchecked.
XCode 4 note: adding the files is different in Xcode 4 - first, make sure your ShareKit project window is closed, then you drag the ShareKit.xcodeproj file (from a Finder window) to your project. You should see the ShareKit's proj tree open up within your project in XCode, and then you should be able to drag ShareKit group as stated above. You then must remove ShareKit.xcodeproj (whole ShareKit project) from your project, so that it does not interfere with your project.
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)
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.
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). Be sure to delete them from Xcode project only, not from the tree (filesystem), so that it does not interfere with git updates. 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].
- If you delete the 'Email' action, you'll also need to comment out the '#import "SHKMail.h"'.....
Build your project. If it won't build, try these troubleshooting steps.
ShareKit, and the submodules used by ShareKit, uses manual reference counting and therefore won't compile in projects that use Xcode 4's new Automatic Reference Counting. If you're getting ARC errors:
- In your target settings, under "Build Phases", expand the "Compile Sources" section.
- Select the all of the files* that are causing you problems and hit 'return' (Don't double-click.)
- Paste this flag (even if Xcode isn't showing you the editing field) and hit 'return':
-fno-objc-arcto disable ARC for those files.
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.
See the Configuration page.
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.
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];
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]