MWOpenInKit is an easier way to handle third-party URL schemes in iOS apps.
Linking to third-party apps is essentially broken on iOS. Let's say that, as a developer, you want to allow users to open map links in Google Maps instead of the built-in Maps.app. You now need to write a whole bunch of custom code that determines whether Google Maps is installed, ask the user which they would prefer, and ideally remember that preference.
If we take a more complex example, like Twitter clients, you're now potentially managing a dozen different third-party URL schemes that are all drastically different and quite possibly poorly-documented.
As a result, very few apps link to external third-party apps for tasks handled by Apple's easier-to-link-to apps, even when users prefer third-party apps.
MWOpenInKit attempts to solve this problem.
For users, it provides a beautiful selection interface to choose which third-party app to perform an action in.
For developers, it provides:
-
An elegant, cohesive API based on semantic actions. Instead of manually constructing URLs, just tell it what you're trying to do. Instead of manually checking which applications a user has installed, let MWOpenInKit automatically query the device for you to figure out what applications are available to perform a given action.
-
A unified, human-readable repository of third-party URL schemes. Every application's URL scheme is just a plaintext plist. You can add support for your application to MWOpenInKit without writing a single line of code.
MWOpenInKit is easiest to install using CocoaPods. Just add the following to your Podfile.
pod "MWOpenInKit"
After running pod install, you should be able to #import <MWOpenInKit/MWOpenInKit.h> inside your application code and go to town.
IMPORTANT
MWOpenInKit hasn't actually been published to CocoaPods yet. For now, if you want to use MWOpenInKit, clone this repo and point your Podfile to the checked-out copy using the :path specifier:
pod "MWOpenInKit", :path => "/some/path/to/MWOpenInKit"
This README will be updated when that changes.
In its simplest form, to use MWOpenInKit you just need to instantiate a handler object and then tell it an action to perform. Here's how you'd open a URL in an external web browser:
MWBrowserHandler *browserHandler = [[MWBrowserHandler alloc] init];
[browserHandler openURL:[NSURL urlWithString:@"http://google.com"]];If the user only has MobileSafari installed, [browserHandler openURL:] will open up Safari for you, just like if you had called [[UIApplication sharedApplication] openURL:] directly.
If the user has multiple web browsers installed, [browserHandler openURL:] will return a UIActivityViewController to be presented (per Apple's documentation, it's recommended you present it modally on iPhone and in a UIPopoverController on iPad). When the user selects an app, it will automatically be updated.
There are a number of different handler objects, all grouped by the type of application. For exampe, MWBrowserHandler, MWMapsHandler, and MWTwitterHandler handle opening links in web browsers, mapping applications, and Twitter clients, respectively.
Some handlers have optional configuration parameters. For example, when linking to a map application, you can specify where the map should be centered and how zoomed-in it should be; these options will take effect whether you're searching for a location, getting turn-by-turn directions, or doing any other action supported by the handler.
MWMapsHandler *mapsHandler = [[MWMapsHandler alloc] init];
mapsHandler.center = CLLocationCoordinate2DMake(42.523, -73.544);
mapsHandler.zoom = 14;
[mapsHandler directionsFrom:@"Washington Square Park" to:@"Lincoln Center"];For an up-to-date list of available handlers and what methods and configuration options are supported by each, check the documentation in the docs directory.
Exhaustive documentation (generated using appledoc) can be found in the docs directory.
A demo app has been provided so you can see MWOpenInKit in action.
- Clone this repo
- Open
MWOpenInKitDemo.xcworkspace - Build and run the app
The demo lets you perform any of the actions supported by MWOpenInKit.
If you only have one app installed capable of performing a task, MWOpenInKit will by default open up that app directly rather than prompt the user to pick. In the demo app, there is a toggle to always show the selection UI. It's recommended that you run the demo on an actual iOS device that has third-party apps installed, but if you must run it in the simulator that toggle will let you see what the selection UI looks like.
Extending MWOpenInKit to include your own application's URL scheme is easy.
-
Inside the
/MWOpenKit/Apps/directory, create a new directory with the name of your app. -
Inside that directory, create a plist. Its name should be the name you want displayed, and it should contain a dictionary. Each key is the signature of a method in the appropriate
MWHandlerobject, and the key is a template string used to generate a URL for that method, where variables wrapped in{handlebars}will be interpolated at runtime.
As much as possible, the template variable keys are named the same as the parameter names of the corresponding Objective-C methods, but there's nothing enforcin that. I'd recommend looking at other plist files in the directory to see what the correct method keys and template keys are.
- Your app's icon goes in the same directory. You will need four copies of the icon, all with the same root name as your plist file:
AppName.png: 60x60[email protected]: 120x120AppName-iPhone.png: 76x76[email protected]: 152x152
These will all be shown as-is, so they should be prerendered. The root filename ("AppName" in those examples) must exactly match the filename of the plist.
- Submit a pull request! There is no need to manually add any of the files to Xcode.
Make sure to try it out first using the demo app to make sure that it works. If this project becomes sufficiently popular, it is likely I'll build a linting tool.
Mike Walker
MWOpenInKit is available under the MIT license. See the LICENSE file for more info.