OvershareKit

A soup-to-nuts sharing library for iOS.

NOTA BENE: OVERSHAREKIT IS NO LONGER UNDER ACTIVE DEVELOPMENT. SEE http://blog.jaredsinclair.com/post/90064823470/oversharekit-to-be-maintenance-only-for-ios-8

Why OvershareKit?

Sharing is far too cumbersome to implement on iOS. UIActivityViewController is too limiting, and rolling your own library is too time-consuming. Most devs end up settling for underwhelming sharing options for lack of the time or inclination to make something better.

OvershareKit makes it trivial to add rich sharing options to your iOS apps. In a word, OvershareKit has everything:

Beautiful share sheets with pixel-perfect, full-color icons in a simple layout.
Lots of tweakable options, including a gorgeous dark mode.
Built-in integration with iOS Twitter and Facebook accounts.
Built-in integration with popular third-party services like App.net, Instapaper, and more.
Complete multi-account management, including authentication and storing credentials securely in the Keychain.
Killer text editing views with as-you-type Twitter syntax highlighting, Riposte-style swipe gesture cursor navigation, and automatic smart quotes.

Screenshot

Pull Requests and New Features

We happily accept any pull request that adds meaningful value for the OvershareKit community. Bug fixes can be submitted on any branch, but significant changes and new features must be submitted on the dev branch for wider testing and review. Our day-to-day work is done on the dev branch. Watch the dev branch for an idea of what’s coming.

OvershareKit also has a public Pivotal Tracker project available here.

How to Use OvershareKit

OvershareKit is designed to be dead simple for the easy cases, while still being flexible enough to scale up to more complex needs, and without breaking inbetween.

After including OvershareKit in your Xcode project (see the detailed requirements below), the steps to get started couldn't be easier:

Create an instance of OSKShareableContent, ideally via one of the convenient class-level constructors like contentFromURL:
Pass that shareable content to the OSKPresentationManager via one of the presentActivitySheetForContent: methods.
There is no step 3.

OvershareKit Versus UIActivityViewController

We are frequently asked why someone would use OvershareKit instead of UIActivityViewController (UIAVC) and UIActivity. UIAVC is great for apps that know they’ll never have a need for any of the following:

Never need to integrate with more than one or two third party services.
Never need to tweak the UI for the activity sheet and sharing screens.
Never care to provide separate, media-specific content for each sharing type (email versus SMS, etc.)
Never need to have multiple items such as a Copy Text versus a Copy Link in the same sheet.
Don't mind that all non-system-provided activities get stuck with boring monochromatic icons.

Many apps can't fit comfortably within those restrictions, which is why we made OvershareKit.

The most important difference between UIAVC and OvershareKit is in how content is structured. UIAVC uses unstructured arrays of content (which contain one or more of a grab-bag of objects, usually strings, images and URLs). UIAVC lets each UIActivity decide which of these objects, if any, it will act upon and how. The shortcoming of this API design is that activities don't know anything about the context in which a sharing session is taking place. For example, the formatting for an email message generated from an Instagram post should look very different from an email generated from an RSS article. But with UIAVC, there's no easy way to communicate that context. Most crucially, it is impossible to do this using UIAVC without providing substitutes for the system-provided mail activities.

Activities should not be given that much responsibility over content. The content should be ready to consume before it is handed to an activity. Furthermore, the content should be formatted in a manner that is appropriate to each type of activity.

This is why OvershareKit uses an instance of OSKShareableContent that bristles with many flavors of OSKShareableContentItem. This API design allows the part of your app that has knowledge of context to prepare all the various types of OSKShareableContentItems before handing it off to an OvershareKit sharing session. This results in a more satisfying sharing experience for the user, and less overall hassle for the developer.

Architecture

OvershareKit has lots of classes, but here are the main players:

OSKPresentationManager: This singleton instance manages the user-interface layers of OvershareKit. It's the class you access to present activity sheets (share sheets). It's also how you can customize the UI of OvershareKit, via four delegates, each for different customization purposes: a style delegate, a color delegate, a localization delegate, and a view controller delegate. If you already like the default look & feel of OvershareKit, you probably won't need to implement any of these delegates.
OSKActivitiesManager: This singleton instance handles model level logic around sharing activities. Unless you're writing your own view controllers, you probably won't need to access this class much (except to provide application-specific third-party credentials, see Authentication section below).
OSKActivity: This semi-abstract base class is the heart and soul of OvershareKit. All sharing activities inherit from it. OvershareKit comes with lots of built-in subclasses of OSKActivity. You can easily write your own subclasses, too. Activities provide important information about how they perform their tasks via lots of required methods.
OSKShareableContent: is the highest-level OvershareKit model object for passing around shareable content. It's sole purpose is to bristle with subclasses of OSKShareableContentItem, making it easy to pass many flavors of content in a single method argument.
OSKShareableContentItem: represents the user's data in a structured, readable, portable way. It is an abstract base class with many subclasses. Because each kind of OSKActivity requires different bits of data and metadata, there is an OSKShareableContentItem subclass for each conceivable type of activity. Think of OSKShareableContentItem like UINavigationItem or UITabBarItem. Navigation controllers and tab bar controllers use those items to keep title and toolbar item changes in sync with child view controller changes. It’s a convenient paradigm that is useful for our purposes, too. OSKShareableContent (see above) has many OSKShareableContentItem subclass properties like emailItem, microblogPostItem, webBrowserItem, etc.
OSKManagedAccount: Third-party accounts (like App.net accounts) are represented in OvershareKit by instances of OSKManagedAccount. OvershareKit manages the creation, authentication, and storage of these accounts. This class is not intended to be subclassed. OvershareKit does not create managed accounts for services that are managed at the system level (i.e. Twitter or Facebook).
OSKManagedAccountStore: This singleton instance manages storing and organizing all the OSKManagedAccounts for activities tied to third-party services.
OSKSystemAccountStore: This singleton instance manages access to system-level accounts like Twitter and Facebook.

Authentication

For the most part, OvershareKit will handle all aspects of authentication by itself. There are several crucial exceptions to this which every app will need to be configured to handle:

Application-Specific Credentials

Some third-party services require application-specific credentials in order to authenticate user actions. The sample app that ships with OvershareKit has been configured to use some test app credentials if the compiler flag for DEBUG is set to 1.

You must not ship OvershareKit's test credentials in a production application. They may be revoked at any time. We will not be responsible for any consequences if that happens. Please see the next several paragraphs for more information on setting up application credentials.

You can provide your app's credentials via the customizationsDelegate property of OSKActivitiesManager. These credentials are represented by instances of OSKApplicationCredential.

The list of services currently requiring application credentials are:

App.net: App.net posting requires an application ID. Visit http://developers.app.net for more information. You will need to create a developer-tier account to register your app (currently