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
Table of Contents
- Why OvershareKit?
- Pull Requests and New Features
- How to Use OvershareKit
- OvershareKit Versus UIActivityViewController
- Application-Specific Credentials
- URL Schemes
- In-App Purchases
- So Much More
- Apps Using 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.
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
Pass that shareable content to the
OSKPresentationManagervia one of the
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.
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
OSKActivityrequires different bits of data and metadata, there is an
OSKShareableContentItemsubclass for each conceivable type of activity. Think of
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
OSKShareableContentItemsubclass properties like
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.
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:
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
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
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 $99 USD per year). Don't forget: registering your app with App.net may also entitle you to participate in the Developer Incentive Program ($$$). Contact App.net for more information. You will also need to register the default redirect URI for OvershareKit:
http://localhost:8000. The other app-specific details they require (like a bundle identifier) are unique to your registered application. Note: if you want your users to also be able to sign in via the App.net Passport application, you'll need to follow App.net's instructions for setting up a custom URL scheme.
Pocket: Visit http://getpocket.com/developer/ for more information. In addition to registering your app, you'll need to follow their instructions for setting up a custom URL scheme, including downloading the Pocket iOS SDK. There is no way to sign into Pocket without setting up this URL scheme.
Facebook: The iOS authentication requirements for Facebook include passing an application ID. Register your app at http://developers.facebook.com/.
Readability: You'll need to obtain an application key and secret by registering your app via a new developer account. Visit http://www.readability.com for more information.
Google Plus: You'll need to obtain an application key by registering your app with Google Plus.
If you have any questions about this setup process, don’t hesitate to ask.
App.net Passport: The App.net Passport app allows users to sign in without having to type their username and password. This option is automatically enabled by OvershareKit whenever the application is installed. You will need to include the App.net Login SDK in your project. You'll also need to set up a custom URL scheme according to App.net's instructions in order for this method to function properly. If you don't set up the URL scheme, users will be prompted to sign in via OvershareKit's web view.
Pocket: Pocket authentication requires setting up a custom URL scheme according to their instructions. You'll also need to include the Pocket-iOS-SDK to enable Pocket sign-in.
OvershareKit is almost entirely a standalone library. All of its categories and classes have been properly namespaced with the
OSK prefix to avoid collisions.
There are two required external libraries, which are included as git submodules in the Depedencies directory:
The Google Plus framework in the Dependencies directory is not a submodule.
You can optionally configure certain activity types to require in-app purchase. OvershareKit does not handle purchasing or receipt validation, but it does handle the logic around presenting your custom purchasing view controller at the appropriate time. OvershareKit will even badge the activity icons with cute little price tags when they have not yet been purchased. See the header files for
OSKPurchasingViewController for more details.
So Much More
There’s a ton of stuff to work with in OvershareKit. All of the major and many of the minor classes have been documented with appledoc syntax. More documentation is coming. If you have questions, please reach out to us.
Justin is an independent iOS and Mac app developer at Second Gear. He is a frequent public speaker at tech events.
Apps Using OvershareKit
Recent additions are at the top of the list.
A Reddit client for iOS 7.
By Craig Merchant
Website | App Store
OvershareKit contains portions of other open-source code, either verbatim or (more commonly) with some pruning and refactoring. The following projects were immensely helpful:
DerpKit: By Steve Streza. Objective-C categories and subclasses of things that should be in Foundation and other frameworks On GitHub
AFNetworking: By Mattt Thompson. A delightful iOS and OS X networking framework. On GitHub
UIColor-Utilities: By Erica Sadun. Helpful utilities for UIColor for iPhone. On GitHub
TwitterText: By Twitter. An Objective-C implementation of Twitter's text processing library On GitHub
Gist 1102091: By Ole Zorn. Creating arbitrarily-colored icons from a black-with-alpha master image (iOS). On GitHub
UIDevice-Hardware: By InderKumarRathmore. This category helps to check the hardware version[s] of [iOS devices]. On GitHub
RPSTPasswordManagementAppService: By Riposte LLC. An iOS utility class for launching 1Password via URL schemes. On GitHub
The MIT License (MIT)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.