Support

AddThis for iOS Documentation

Quickstart Guide | Documentation

The AddThis iOS SDK allows native iOS application developers to share content to destinations across the web, much as the Javascript library allows web developers to share content from their web applications. The iOS SDK also has support for sharing image data directly to services that support it. As with all AddThis offerings, we're developing analytics reports to help you understand how your content is being shared.

Please refer to the Quick Start Guide to get up and running quickly with the SDK, including registration, obtaining application IDs, and setting up any necessary service-specific keys.

 

What Can Be Shared?

The iOS SDK, like the AddThis web tools, primarily supports sharing URL-based content. That is, you are sharing a URL that is publicly navigable. Many services are also able to inspect URLs to provide rich preview and other media-related capabilities.

The SDK also allows you to share image data directly to a subset of services that support it.

 

Performing Sharing Operations

The SDK is set up to allow you to include sharing in your application in a few different ways, with varying degrees of customization. Generally, the use-cases are:

  • Share Button: You include an AddThis sharing button in your application in a specified location. This button invokes a menu of personalized choices for the user.
  • Share Menu: You invoke the AddThis sharing menu from your application at a specified location. This is similar to the button mode, but the trigger that invokes the menu is your own.
  • Custom Share Menu: You obtain the appropriate list of services from the SDK, then build your own sharing menu for the user.
  • Service-Specific Share Triggers: you build your own interface to present sharing options, and use the SDK only to initiate the share to a specific service

No matter which method you chose to use to integrate sharing into your application, URL tracking will be enabled and any library-defined customizations will be honored.

Share Button

You can include the default AddThis share button, which will render the full sharing menu when clicked, in your view as follows:

[AddThisSDK showAddThisButtonInView:aview
	withFrame:CGRectMake(75, 50, 150, 50)
	forURL:@"http://www.example.com"
	withTitle:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];

Share Menu

You can include the AddThis sharing menu directly, rendering it from within your own UI control callback, like this:

[AddThisSDK presentAddThisMenuForURL:@"http://www.example.com"
	withTitle:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];

If you want to show the menu in a popover view, for iPad, use instead:

[AddThisSDK presentAddThisMenuInPopoverForURL:@"http://www.example.com"
	fromRect:yourRect
	withTitle:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];

here yourRect is a position on the main UIWindow.

Custom Share Menu

To skip the AddThis sharing button or menu altogether, and just use AddThis to share directly to a specific service from your own UI callback, do the following:

[AddThisSDK shareURL:@"http://www.example.com"
	withService:@"twitter"
	title:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];

This method returns a dictionary that contains the status of the call: Status, StatusCode and Description (only in the case of an error). The status codes can be found in the enum ATStatusCode.

Sharing Images

You can share image data in much the same way that you can share URLs – the general API support model is identical, though in general you will pass a UIImage object in place of the urlstring parameter, and the method will be named slightly differently.

Note that not all services support image sharing, so you do need to be attentive when invoking individual services directly. Also, sharing of images to Facebook requires Connect, and Twitter requires OAuth and Twitpic, so if you wish to use these services you need to configure those services.

The corresponding image sharing methods are given below:

[AddThisSDK showAddThisButtonInView:view
	withFrame:CGRectMake(75, 50, 150, 50)
	forImage:[UIImage imageNamed:@"image.jpg"]
	withTitle:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];
[AddThisSDK presentAddThisMenuForImage:[UIImage imageNamed:@"image.jpg"]
	withTitle:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];
[AddThisSDK presentAddThisMenuInPopoverForImage:[UIImage imageNamed:@"image.jpg"]
	fromRect:yourRect
	withTitle:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];
[AddThisSDK shareImage:[UIImage imageNamed:@"image.jpg"]
	withService:@"twitter"
	title:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];
 

About Sharing Services

The AddThis iOS SDK supports a large variety of services – places to which you can send content.

Service Types

There are generally four different types of sharing services supported:

Browserless Services

Services that support some type of direct sharing option, leveraging iOS libraries, direct integrations, and some likely authentication step. Services in this category include:

  • Facebook (optionally uses Connect, requires some setup)
  • Twitter (optionally uses OAuth, requires some setup)
Native Device Services

Some services are native on the device. These include:

  • Native email (user has to setup an email account in the device to use this)
Browser-based Services

All other services fall into this category; the share takes place in an embedded web view, invoking the OExchange-compliant AddThis Sharing API and with a look and feel similar to the default experience of the AddThis in-page tools. Services in this category include all services supported by the AddThis platform.

Image-aware services

Additionally, some services can support receiving image data rather than URLs. This is a different model, and does not include analytics, but may prove useful in some cases. Services in this category include:

  • Facebook
  • Tumblr
  • Native email
  • Twitter (through Twitpic)

Controlling the Services in the Sharing Menu

The full sharing menu includes a default list of services, determined by AddThis. These services can be modified by the user to better fit their personal preferences. You can also explicitly control the services presented here via setFavoriteMenuServices.

You can also set a list of services as blacklisted using the call: setBlackListedServices. The blacklisted services will not be shown in the service menu list and direct sharing to these services will give an error condition.

Obtaining Services

Certain services are included in native code and are not dynamically included. The SDK obtains the list of other available backend services from the AddThis service API, caching results for 30 days. If you would like to force a refresh of this supported service list, the updateServiceList call will do so. You can also disable automatic updates of the service list via a call like [AddThisSDK enableAutomaticUpdate:NO];.

If you are building your own sharing menus and just want to obtain available services from the library, you can fetch them like so:

NSArray *allServices = [AddThisSDK getAllServices];

This will will return you an array of dictionaries, each containing Name, ServiceCode and ImageData. These keys represent the name of the service (as an NSString), service code (as an NSString) and the icon image data (as NSData) respectively. To share to a particular service you can use:

[AddThisSDK 
	shareURL:@"http://www.myshareurl.com"
	withService:@"twitter"
	title:@"Check this out"
	description:@"Lorem ipsum dolor sit amet, consectetuer adipisci"];


Configuration and Customization

The SDK supports a variety of configuration and customization features, all generally accessed via properties on the library itself.

Orientation Change Support

The SDK can gracefully handle orientation changes on the device. If your app does not support orientation changes, set the autorotate property of the library to NO (shouldAutoRotate), and set the orientation your app uses in setInterfaceOrientation, like so: [AddThisSDK shouldAutoRotate:NO];
[AddThisSDK setInterfaceOrientation:UIInterfaceOrientationPortrait];

Basic Look-and-Feel Customization

[AddThisSDK canUserEditServiceMenu:YES];
Determines whether the user is able to edit the favorite services menu. If so, the user can add new services, reorder services, or delete services.

[AddThisSDK canUserReOrderServiceMenu:YES];
Determines whether the user can reorder services in the menu; will have no effect if canUserEditServiceMenu is set to NO.

[AddThisSDK setNavigationBarColor:color];
Sets the color of the navigation bar used in the menu. 'color' should be a UIColor object.

[AddThisSDK setSearchBarColor:color];
Sets the color of the search bar used in the menu. 'color' should be a UIColor object.

[AddThisSDK setToolBarColor:color];
Sets the color of the toolbar used in webviews. 'color' should be a UIColor object.

[AddThisSDK setMenuTextColor:color];
Sets the color of the text in each cell of the table views. 'color' should be a UIColor object.

[AddThisSDK setMenuBackground:color];
Sets the color of the table cell background. 'color' should be a UIColor object.

[AddThisSDK setModalPresentationStyle:UIModalPresentationFormSheet];
Sets the presentation style of the modal view for iPad devices. Options are UIModalPresentationFullScreen, UIModalPresentationPageSheet, UIModalPresentationFormSheet, UIModalPresentationCurrentContext.

[AddThisSDK setFavoriteMenuServices:@"facebook",@"twitter",nil];
Configures the favorites menu with specific services, in this case 'facebook' and 'twitter'. If not called, the default list from the database is used.

[AddThisSDK setBlackListedServices:@"facebook",@"twitter",nil];
Sets the services given as blacklisted. These services will not be shown in the service menu and direct sharing to these will return an error condition.

[AddThisSDK setTableStyle:UITableViewStyleGrouped];
Sets the UITableViewStyle of the menu tableview. You can choose between UITableViewStylePlain and UITableViewStyleGrouped.

[AddThisSDK setMenuCellTextAlignment:UITextAlignmentCenter];
Sets the text alignment in the menu to centered. This method is used to horizontal alignment of the text in menu and take any value from UITextAlignment.

[AddThisSDK setMenuFont:font];
Sets the font size of menu to the value given. The 'font' should be an object of UIFont.

[AddThisSDK setMenuCellBorderColor:color];
Sets the border color of each cell in the menu to the given color. 'color' should be a UIColor object.

[AddThisSDK setMenuCellHeight:height];
Set the menu cell height to the float value 'height'

[AddThisSDK shouldShowMoreView:NO];
Set this value to NO if you do not want to show the 'More' services in AddThis Menu.

Twitter via text

[AddThisSDK setTwitterViaText:@"addThis"];
The text assigned here will be the via text shown along with the tweets. The default value is addthis.


Configuring Service Keys

To leverage the native integrations with Facebook and Twitter, you need to provide your Facebook and Twitter API keys. To share images to Twitter, you'll also need to provide your TwitPic key.

Providing your Facebook key

To use Facebook Connect-enabled sharing, you'll need to tell the library to do so, and then configure your Facebook API key. You can do both as follows:

[AddThisSDK setFacebookAuthenticationMode:ATFacebookAuthenticationTypeFBConnect];
[AddThisSDK setFacebookAPIKey:@"yourkey"];

If you don't have a Connect key already, get one from Facebook.

Providing your Twitter keys

To use Twitter OAuth-enabled sharing, you'll need to tell the library to do so, and then configure your Twitter consumer key, consumer secret, and callback URL. You can do both as follows:

[AddThisSDK setTwitterAuthenticationMode:ATTwitterAuthenticationTypeOAuth];
[AddThisSDK setTwitterConsumerKey:@"yourconsumerkey"];
[AddThisSDK setTwitterConsumerSecret:@"yourconsumersecret"];
[AddThisSDK setTwitterCallBackURL:@"yourcallbackurl"];

If you are not already set up with a Twitter key and secret, follow these steps to get the keys and to set the callback URL. You should select 'browser' as the application type when asked. Note that the callback URL doesn't need to be an existing URL, but it should be entered.

If you also want to share an image through Twitter, which will internally use TwitPic, you should obtain and then provide your TwitPic API key to the library:

[AddThisSDK setTwitPicAPIKey:@"yourApiKey"];

Logging out

To logout the user from a particular service use:

[AddThisSDK logout:serviceCode];

You can also invalidate all the logged-in sessions in one go by using the method logoutAll

[AddThiSDK logoutAll];
 

API Delegate

You can get callbacks when a share is about to initiate. The delegate method is :
- (void)didInitiateShareForService:(NSString *)serviceCode;
Your class object should be set as the delegate for the SDK using the method setDelegate: to register the callbacks.


Additional Reference

ARC settings

If you are working on a Automatic Reference Counting(ARC) project you will need to set the compiler flag to -fno-objc-arc for every non ARC files.
Navigate to the 'Build Phases' of your project's target settings and add the compiler flag -fno-objc-arc to each library files inside 'Compile Sources'.

Status Codes

typedef enum {
	ATStatusCode_Success = 100,
	ATStatusCode_Error = 400,
	ATStatusCode_NetWorkError = 401,
	ATStatusCode_ImageNotFound = 402,
	ATStatusCode_ImageShareNotSupported = 403,
	ATStatusCode_BlackListedService = 310
}ATStatusCode;

Facebook Authentication Types

typedef enum {
    //uses the default authentication method provided by addthis
    ATFacebookAuthenticationTypeDefault=0, 
    //uses facebook connect
    ATFacebookAuthenticationTypeFBConnect=1 
}ATFacebookAuthenticationType;

Twitter Authentication Types

typedef enum {
    //uses the default authentication method provided by addthis
    ATTwitterAuthenticationTypeDefault=0, 
    //uses OAuth for twitter
    ATTwitterAuthenticationTypeOAuth=1  
}ATTwitterAuthenticationType;
Last Updated: Oct 18, 2013 03:31PM EDT
help@addthis.com
http://assets03.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete