poking a hole in the sandbox: using urls on ios · agiletortoise.com poking a hole in the sandbox:...

agiletortoise.com

Poking a Hole in the Sandbox:Using URLs on iOS

Greg Pierce@agiletortoise

Tuesday, September 11, 12

agiletortoise.com

Who am I?

Greg Pierce

President, Agile Tortoise

@agiletortoisehttp://agiletortoise.com

Indie app development, web consulting


http://agiletortoise.com

http://agiletortoise.com

agiletortoise.com

What do I do?

Drafts PhraseologyTerminology


agiletortoise.com

What am I talking about?

Custom URLs schemes as tool for inter-app communication on iOS.

- Limited options in the sandbox.

- Consume URLs in other apps.

- Provide services with URLs.


agiletortoise.com

Inter-app whaaa?

Integrating with other apps can make your app...

- More useful.

- Offers great opportunities for cross-promotion.


agiletortoise.com

Overview

Part 1 - What? - Local and Lightweight

Part 2 - Why? - Use Cases

Part 3 - How? - Implementation

Part 4 - X-Callback-URL

Q & A


agiletortoise.com

Part 1 - What?

Local and Lightweight


agiletortoise.com

Anatomy of a URL

- URL = Uniform Resource Locator

- “scheme” or “protocol” is registered with OS.

- Safari registers “http”- Phone.app registers “tel”- Mail.app registers “mailto”

scheme://domain:port/path?query_string#fragment_id


agiletortoise.com

Custom URLs

- iOS provides means to register “Custom URL schemes” for apps.

- Registering says you know what to do with “scheme:” URLs.

- Simple entries in app’s Info.plist.

- One app can register many custom URL schemes.


agiletortoise.com

URLs

- Lightweight Messaging between apps. - No OAuth, Web Services, complex setup.

- Local

- No network require for locally installed apps.

- Few options!


agiletortoise.com

Custom URL structure

- Beyond the scheme and the colon, custom URL can look like anything.

- Not tied to HTTP (host:port/path) structure, but... - reuse tools/code that already exist to parse. - easier to document/consume.

- Must follow escaping/encoding guidelines- Can support 80k characters at least.

scheme:*


agiletortoise.com

Using URLs

- URLs can be triggered like any links

- Link embedded on a webpage

- Programmatically – two important methods:

[[UIApplication sharedApplication] canOpenURL:(NSURL *)url];

[[UIApplication sharedApplication] openURL:(NSURL *)url];


agiletortoise.com

What happens?

When a custom URL is opened...

- Source app is backgrounded.- Target app is launched (or foregrounded)- Target AppDelegate is notified with a URL, using...

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation


agiletortoise.com

Part 2 - Why?

Use cases


agiletortoise.com

Testing if app is installed

If you register a unique URL scheme, you give other apps a way to test if your app is installed.

This includes your own apps...great for cross-promoting apps, without annoying people who have already downloaded.


agiletortoise.com

Launching

Without any additional work, registering a URL scheme gives apps a way to launch your app.

See Launch Center Pro from App Cubby...


agiletortoise.com

Launching with Context

Have the user arrive at a specific place in your app...

Facebook: fb://profile fb://events

Tweetbot: tweetbot://post


agiletortoise.com

Launching with Content

Send some bit of string data to the target app.

Drafts drafts://x-callback-url/create?text=%@

OmniFocus omnifocus:///add?name=%@


agiletortoise.com

Executing an Action

Dial a phone number

Open this URL, Phone.app will launch and dial the number.

tel:8175551234


agiletortoise.com

Two-Way Interaction

- All these examples are one-way.

Source App > Target App

- What about 2-way?

Source App > Target App > Source App

- Callback URLs


agiletortoise.com

Instapaper > Terminology > Instapaper

terminology://x-callback-url/lookup? text=ceremony &x-source=Instapaper &x-success=instapaper://


agiletortoise.com

Instapaper > Terminology > Instapaper

Terminology does the “lookup”

x-source param provides friendly name for source

Tap and Terminology will trigger the url in the x-success param


agiletortoise.com

Two-Way with Data - Terminology Replaceterminology://x-callback-url/replace? text=Select &x-success=drafts://x-callback-url/replaceSelection &x-source=Drafts &x-cancel=drafts://

drafts://x-callback-url/replaceSelection &replaceWith=choose

drafts://


agiletortoise.com

Other Two-Way

- iZettle

- Credit Card Transactions

- Scanner Go

- Bar Code Scanning

- Authorization

- Dropbox SDK, Facebook SDK


agiletortoise.com

What not to do with URLs

- Destructive actions

- If destructive, require user confirmation.

- Think about HTTP GET RESTful actions.

myapp://deleteEverything


agiletortoise.com

Part 3 - How?

Implementation


agiletortoise.com

URLScheme Demo App

Example app on Github

https://github.com/agiletortoise/URLSchemes




agiletortoise.com

Consuming URLs


agiletortoise.com

Building URLs#import "Scratchpad.h"#import "NSString+URLEncoding.h" // Category for encoding

@implementation Scratchpad- (void)examples{ NSString *urlString = @"test://action?param1=%@&param2=%@"; NSString *p1 = @"Hello World"; NSString *p2 = @"You’re Awesome"; NSString *fullURLString = [NSString stringWithFormat:urlString,

[p1 urlEncodeUsingEncoding:NSUTF8StringEncoding], [p2 urlEncodeUsingEncoding:NSUTF8StringEncoding]];

NSURL *url = [NSURL URLWithString:fullURLString];}@end

test://action? param1=Hello%20World &param2=You%E2%80%99re%20Awesome


agiletortoise.com

Opening URLs

- Use canOpenURL to build UI, don’t show things that can’t be used.

- canOpenURL doesn’t need full URLs, test with just “scheme://”

if ([[UIApplication sharedApplication] canOpenURL:url]) { [[UIApplication sharedApplication] openURL:url];}


agiletortoise.com

Providing URLs


agiletortoise.com

Register scheme


agiletortoise.com

Register in Info.plist


agiletortoise.com

Valid URL Scheme Names

- Sequence of characters beginning with a letter and followed by any combination of letters, digits, plus ("+"), period ("."), or hyphen ("-").

- NOT case sensitive.


agiletortoise.com

Recommended URL Scheme Names

- Your app name as it appears on the device, with hyphens in place of spaces.

My App Name⬇

my-app-name://


agiletortoise.com

Versioning

If you provide actions that you need to version over time, register additional URLs

x-app-api10://x-app-api20://

Now you have a way to test for compatibility.


agiletortoise.com

Reacting to URL

On AppDelegate, define:

c

- called after applicationWillEnterForeground- called before applicationDidBecomeActive- return NO if you don’t recognize the URL - (Nothing happens, just best practice)

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation;


agiletortoise.com

iOS 3 note...

Prior to iOS 4, you handled URLs in....

If you need to support iOS 3, implement this method and forward to your application: openURL: sourceApplication: annotation method.

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url;


agiletortoise.com

Parsing Parameters

URLParser *parser = [[URLParser alloc] initWithURLString:[url absoluteString]];NSString *testParamValue =

[parser valueForVariable:@"test"];// testParamValue == @”param value”

myapp://actionName?test=param%20value&test2=paramValue


agiletortoise.com

Parsing Parameters

If you parse using some other method, USE THIS METHOD TO DECODE!!!

[str stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding]


agiletortoise.com

DEMO

(unreheased, apologies in advance)


agiletortoise.com

Part 4

X-Callback-URL


agiletortoise.com

X-Callback-URL

- Specification to standardize URL formats

- Drafts, Terminology, Instapaper, Agenda, Due, iCab Mobile, Poster, Phraseology, Notesy.

- Collaboration of myself, Marco Arment with input from a few others.

http://x-callback-url.com




agiletortoise.com

X-Callback-URL format

- [action] is specific to your app/implementation and should typically be a verb.

- [action parameters] are also specific to your app and show be in a URL query string...i.e.:

subject=The%20Subject&body=The%20Body

scheme://x-callback-url/[action]?[x-callback parameters]&[action parameters]


agiletortoise.com

X-Callback-URL Parameters

x-source: Friendly name of source app.

x-success: Base URL to fire if successful

x-error: Base URL to fire if error occurs

x-cancel: Base URL to fire if user cancels


agiletortoise.com

Finally....

- Why use URL schemes? Why not?

- Why format them with X-Callback-URL? Why not?

- Document what you implement!!!!!!

- Use affiliate links to promote apps you integrate with!!!!!

- UTF8 escape and decode parameters!

- Test with Unicode chars and cold starts.


agiletortoise.com

Resources

Find URL schemes:- http://handleopenurl.com- http://wiki.akosma.com/IPhone_URL_Schemes

Tutorial:- http://mobile.tutsplus.com/tutorials/iphone/ios-sdk-working-with-url-schemes/ X-Callback-URL:- http://x-callback-url.com (sample apps/examples)

URLSchemes Demo App:- https://github.com/agiletortoise/URLSchemes


http://handleopenurl.com

http://handleopenurl.com

http://wiki.akosma.com/IPhone_URL_Schemes

http://wiki.akosma.com/IPhone_URL_Schemes



agiletortoise.com

Q & A@agiletortoise

Slides and Links:http://agiletortoise.com/blog


http://agiletortoise.com/blog

http://agiletortoise.com/blog

poking a hole in the sandbox: using urls on ios · agiletortoise.com poking a hole in the sandbox:...

Documents