ShareThis | Mobile API

Mobile API

Overview
Setup for IOS Platform
Usage
Supported Social Networks & User Authentication
Customizing the Share UI
Resource List
API Reference

Overview

Consumers are increasingly using their smart-phones to browse content on the web through browsers and/or applications. ShareThis provides a set of re-usable services to application developers to enable sharing of specific content within applications with their friends on social networks. The shareable content can be anything from videos, photos, game scores, to any content that is addressable as a URL on the Internet. The services are designed to be embedded within applications. Users stay within the application during the sharing process thus providing a simple user experience while staying engaged with the application.

The current version of our mobile sharing services supports the IOS platform (iPhone & iPad). We plan on supporting Android in the near future. For application developers, we provide a simple way to integrate rich sharing capability into their applications without the need to understand and support user-authentication on social networks, and handling sharing workflows. Developers include our library into their projects and invoke our sharing service when needed in their application; all in a few lines of code. ShareThis handles the rest.

Setup for IOS Platform

To include the ShareThis library in your project, first download the package. Uncompress the package; a folder "ShareThis" is created containing separate sub-folders for development ("simulator") and deployment ("device"). Choose the appropriate sub-folder to find all code assets (.h, .a, .xib, and .png) necessary to embed ShareThis into your app.

1. Right click on the root of your project in the Groups & Files panel of XCode and choosing "Add" and then "Existing Files...".
2. Locate and add libShareThis.a, ShareThis.h and other included resources (.xib, .png) into your project.
3. Right click on the root of your project again, choose "Add" and then "Existing Frameworks..."
4. From the dialog box, choose Foundation.framework, MessageUI.framework, and Security.framework from the iOS SDK section and hit Add.

Your project will now build with ShareThis! To use ShareThis in your code, you must make it visible to your project by including the ShareThis.h header file. To do this, you may either include ShareThis.h in each source file that utilizes sharing, or you may include ShareThis.h in your application's pre-compiled header (.pch) file. Because the ShareThis interface is C-based, you can do so without worrying about language compatibility.

Usage

The ShareThis library is packaged as a set of simple C functions to allow for maximum compatibility with many different kinds of applications. This also has the benefit of being very simple to implement.

Before sharing can be performed, the ShareThis library must be given a public key and an access key, which are provided to you by ShareThis when you sign up for the developer program. This can be done with the following example code:

			 
#include "ShareThis.h"

//...my application code...

void initializeShareThis()
{
	STSetPublicKey("1234567890"); //Replace with your public key
	STSetAccessKey("1234567890"); //Replace with your access key
}

To start using the ShareThis library to share, the simplest method of sharing is to set a URL and then share it. If, for example, the goal was to share an application's website, it could be accomplished with the following code:

			 
#include "ShareThis.h"

//...my application code...

void shareMyWebsite()
{
	STSetShareURL("http://www.myapplicationwebsite.com");

	STShare();
}

The first function sets what to share, and the second starts the sharing process. The user will be presented with a menu of sharing services and the ability to specify a comment.
If you would like to include a default comment, the STSetShareComment() function provides such functionality:

			 
#include "ShareThis.h"

//...my application code...

void shareMyWebsite()
{
	STSetShareURL("http://www.myapplicationwebsite.com");
	STSetShareComment("Check out these great apps!");

	STShare();
}

Note that the order of the two set functions is unimportant, but that the share function must come last.
In addition to setting a sharing comment, a subject line can also be included. However, this is only supported by some sharing methods, most notably email.

			 
#include "ShareThis.h"

//...my application code...

void shareMyWebsite()
{
	STSetShareURL("http://www.myapplicationwebsite.com");
	STSetShareSubject("I found a great app company!");
	STSetShareComment("Check out these great apps!");

	STShare();
}

Finally, if your application has a sharing button and you would like the sharing popover menu to appear to pop out from it, the STSetPresentFromView() function allows you to specify this. Simply pass a button or other view to the function and the sharing popover will anchor to that view.

			 
#include "ShareThis.h"

//...my application code...

- (IBAction)share:(UIButton *)a_button
{
	STSetPresentFromView(a_button);

	STSetShareURL("http://www.myapplicationwebsite.com");
	STSetShareSubject("I found a great app company!");
	STSetShareComment("Check out these great apps!");

	STShare();
}

Supported Social Networks & User Authentication

We support Facebook, Twitter, LinkedIn, Email (natively on the phone), Google Buzz, and Yahoo Pulse. Our primary consideration in choosing these services was to post directly to these services without compromising the user experience, and to simplify the support for OAuth authentication through one-time sign-ins. When a user attempts to share from an application, ShareThis checks to see if this user is already signed-in to the chosen social network and will cause authentication through OAuth natively from their social network (e.g. Facebook). Once a user is signed-in through OAuth a ShareThis token is persisted on the device so all applications using the ShareThis sharing service can access the token. Thus, users sign-in once and can share from any ShareThis-enabled application on their device without having to re-authenticate through that application. Since ShareThis manages all user access tokens, developers do not need to consider this aspect when building their applications; ShareThis handles all this in the background.

Customizing the Share UI

The ShareThis library supports reskinning to match your application's appearance. By default, ShareThis will load images from your application's main bundle, although specifying a resource bundle with the STSetResourceBundle() function is a convenient way to separate your skin assets from the rest of your application assets.

Skins may be edited using Interface Builder, which is bundled with Apple's XCode development environment. Some level of familiarity with Interface Builder is assumed here - the Interface Builder documentation is a great resource for beginners.

STServiceMenuView.xib

STServiceMenuView.xib defines the appearance of the list of sharing services that appear when STShare() is called.

STServiceMenuView.xib file owner must be an STServiceMenuViewController object.

STServiceMenuViewController defines several IBActions for sharing, such as shareByEmail:, shareByFacebook:, shareByGoogleBuzz:, shareByTwitter:, and other services supported by ShareThis. Sharing buttons hooked up to these IBActions will instruct ShareThis to begin the sharing procedure for their respective services.

STShareView.xib

STShareView.xib defines the appearance of the sharing view, which allows for comment editing and sending.

STShareView.xib file owner must be an STShareViewController object.

STShareViewController defines several views and IBActions. The m_commentTextView view is an UITextView that will be used for comment display and editing, while m_statusLabel is a UILabel that displays various status information for different services, such as the number of characters entered so far and the maximum number of characters allowed when sharing via Twitter. The IBAction share: should be hooked up to a button labeled "Send" or "Share" or something similar, and is used to send the sharing comment.

Resource List

Resource File	Description
`STButton.png`	The background image used for toolbar buttons in their normal state.
`STButtonDisabled.png`	The background image used for toolbar buttons in their disabled state.
`STButtonHighlighted.png`	The background image used for toolbar buttons in their highlighted (touched) state.
`STIconEmail.png`	The icon used for email sharing.
`STIconFacebook.png`	The icon used for Facebook sharing.
`STIconGoogleBuzz.png`	The icon used for Google Buzz sharing.
`STIconTwitter.png`	The icon used for Twitter sharing.
`STIconYahooPulse.png`	The icon used for Yahoo Pulse sharing.
`STPopoverArrowDown.png`	The down arrow for the ShareThis popover menu, shown when the menu appears above a view.
`STPopoverArrowUp.png`	The up arrow for the ShareThis popover menu, shown when the menu appears above a view.
`STPopoverArrowLeft.png`	The left arrow for the ShareThis popover menu, shown when the menu appears above a view.
`STPopoverArrowRight.png`	The right arrow for the ShareThis popover menu, shown when the menu appears above a view.
`STPopoverBorder.png`	The border of the popover menus used by ShareThis. This image should be a stretchable image (see UIImage documentation for details). The skinning system will use the middle third of the image as the popover body, but because the contents of the popovers is always opaque, this area should simply be transparent. The area around the body will be stretched to fit the popover.
`STToolbarTop.png`	The top toolbar image for the `STShareView` XIB.
`STToolbarBottom.png`	The bottom toolbar image for the `STShareView` XIB.
`STServiceMenuView.xib`	The popover view that appears when selecting a service with which to share.
`STShareView.xib`	The popover view for adding a comment before sharing.

API Reference

Function	Description
`void STSetResourceBundle(void * a_bundleOrNil)`	Sets the NSBundle that contains the skinning resources for the library. The bundle may be set to any bundle in the application, or may be null in order to use the main bundle.
`void STSetPresentFromView(void * a_viewOrNil)`	Sets the view from which the sharing popover view will appear. Setting a view gives the sharing popover an idea of where to appear. If a view is set, the popover will appear anchored to the center of the view, or if no view is set the popover will appear in the center of the screen.
`void STSetPublicKey(const char * a_publicKey)`	Sets the public key used for authenticating your developer identity with ShareThis. Your publisher key provided to you when you register is your public key.
`void STSetAccessKey(const char * a_accessKey)`	Sets the access key used for authenticating your developer identity with ShareThis. Your access key is provided to you by ShareThis when you sign up for the developer program. If you have not received a access key, please contact ShareThis.
`void STSetShareSubject(const char * a_shareSubject)`	Sets the default subject used for sharing. This currently only affects email shares.
`void STSetShareComment(const char * a_shareComment)`	Sets the default comment used for sharing. User may change this comment in the comment box through the pop-over.
`void STSetShareURL(const char * a_shareURL)`	Sets the URL to share.
`void STShare()`	Begins the sharing process with the current sharing data. This should be called after `STSetShareURL()`, otherwise it will perform no action. The user will be presented with series of sharing popovers to allow them to share the URL with their friends on various social networks or email.
`void STResetTokens()`	Resets all user tokens on the device. Note:This function should be used only if the app developer has reason to believe that data integrity of user's linked accounts is compromised. This call clears the local cache and will force re-authentication on subsequent usage.