Skip to content

Latest commit

 

History

History
248 lines (140 loc) · 17.4 KB

README.md

File metadata and controls

248 lines (140 loc) · 17.4 KB
Raw

OvershareKit

A soup-to-nuts sharing library for iOS.

Table of Contents

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:

  1. Create an instance of OSKShareableContent, ideally via one of the convenient class-level constructors like contentFromURL:

  2. Pass that shareable content to the OSKPresentationManager via one of the presentActivitySheetForContent: methods.

  3. 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:

  1. Never need to integrate with more than one or two third party services.
  2. Never need to tweak the UI for the activity sheet and sharing screens.
  3. Never care to provide separate, media-specific content for each sharing type (email versus SMS, etc.)
  4. Never need to have multiple items such as a Copy Text versus a Copy Link in the same sheet.
  5. 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 $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.

URL Schemes

  • 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.

Dependencies

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.

In-App Purchases

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.

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.

Contributors

Jared Sinclair

Jared Sinclair

Primary Author and API Design
Twitter: @jaredsinclair
App.net: @jaredsinclair

Jared is an independent iOS app designer and developer. He makes apps like Unread an RSS Reader and Riposte for App.net.

Justin Williams

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.

Apps Using OvershareKit

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

Attributions

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

License

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.