============
Note: day-to-day work is done on the dev branch. Bug fixes and new features will show up there first.
- Why OvershareKit?
- Screenshot
- How to Use OvershareKit
- Architecture
- Authentication
- Application-Specific Credentials
- URL Schemes
- Dependencies
- In-App Purchases
- So Much More
- Contributors
- Apps Using OvershareKit
- Attributions
- License
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.
Enter OvershareKit.
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.
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 likecontentFromURL:
-
Pass that shareable content to the
OSKPresentationManager
via one of thepresentActivitySheetForContent:
methods. -
There is no step 3.
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 anOSKShareableContentItem
subclass for each conceivable type of activity. Think ofOSKShareableContentItem
likeUINavigationItem
orUITabBarItem
. 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 manyOSKShareableContentItem
subclass properties likeemailItem
,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.
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 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
$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.
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:
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 OSKActivitiesManager
and OSKPurchasingViewController
for more details.
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.
Jared Sinclair — Primary Author and API Design
Twitter: @jaredsinclair
App.net: @jaredsinclair
Jared is an independent iOS app designer and developer. He makes Riposte and Whisper for App.net along with Jamin Guy.
Justin Williams — API Design & iOS Account Integration
Twitter: @justin
App.net: @justin
Justin is an independent iOS and Mac app developer at Second Gear. He is a frequent public speaker at tech events.
Recent additions are at the top of the list.
nvNotes
The professional Note-taking App that allows you to focus on writing.
Website | App Store
Unread
An RSS Reader
By Jared Sinclair
Website | App Store
Redd
A Reddit client for iOS 7.
By Craig Merchant
Website | App Store
Sunlit
Shared photos and stories, built with App.net.
By Manton Reece and Jonathan Hays
Website | App Store
App.net - Broadcast With Push
Never miss important news again with App.net Broadcast.
By App.net
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.