IPhoneURLScheme Reference ios

8/10/2019 IPhoneURLScheme Reference ios

1/16

Apple URL Scheme

Reference


2/16

Contents

About Apple URL Schemes 4

At a Glance 4

Composing Items Using Mail 4

Starting a Phone or FaceTime Conversation 4

Specifying Text Messages 5

Opening Locations in Maps 5

Opening Items in iTunes 5

Opening YouTube Videos 5

Mail Links 6

Phone Links 7

FaceTime Links 9

SMS Links 10

Map Links 11

iTunes Links 13

YouTube Links 14

Document Revision History 15

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

2


3/16

Tables and Listings

Phone Links 7

Listing 2-1 Turning telephone number detection off 8

Map Links 11

Table 5-1 Supported Apple Maps parameters 12


3


4/16

This document describes several URL schemes that are supported by system apps on iOS and OS X. Native iOS

apps and web apps running in Safari on any platform can use these schemes to integrate with system apps

and provide a more seamless experience for the user. For example, if your iOSappdisplays telephonenumbers,

you could use an appropriate URL to launch the Phone app whenever someone taps one of those numbers.

Similarly, clicking an iTunes link, launches the iTunes appandplays thesong specified in the link. What happens

when a user clicks a link depends on the platform and the installed system apps.

This document describes those schemes that require special attributes or special formatting in order to be

understood by the associated system app. As a result, this document does not describe all URL schemessupported on different Apple platforms.

At a GlanceYou should read this document if you want to launch a system app from your iOS or OS X app or from your

web app running in Safari. This document contains both Cocoa Touch sample codeusing the openURL:

method of the sharedUIApplicationobject to open URLsand HTML samples. For more information on

how to use the openURL:method, seeUIApplication Class Reference .

Composing Items Using Mail

Use themailtoscheme to open the Mail app and populate a new email with information.

Relevant Chapter: Mail Links(page 6)

Starting a Phone or FaceTime Conversation

Use thetelandfacetimeschemes to initiate telephone or video conversations.


4

About Apple URL Schemes


5/16

Relevant Chapter: Phone Links(page 7),FaceTime Links(page 9)

Specifying Text Messages

Use thesmsscheme to compose a text message and specify a recipient.

Relevant Chapter: SMS Links(page 10)

Opening Locations in Maps

Use specially formatted URLs to open the Maps app and display directions or locations.

Relevant Chapter: Map Links(page 11)

Opening Items in iTunes

Use specially formatted URLs to open iTunes and display items in the iTunes Music Store.

Relevant Chapter: iTunes Links(page 13)

Opening YouTube Videos

Use specially formatted URLs to open YouTube videos in Safari.

Relevant Chapter: YouTube Links(page 14)

About Apple URL Schemes

At a Glance


5


6/16

Themailtoscheme is used to launch the Mail app and open the email compose sheet. When specifying a

mailtoURL, you must provide the target email address. The following examples show strings formatted for

Safari and for native apps.

HTML link:

John Frank

Native app URL string:

mailto:[email protected]

You can also include a subject field, a message, and multiple recipients in the To, Cc, and Bcc fields. (In iOS,

thefromattribute is ignored.) The following example shows a mailtoURL that includes several different

attributes:

mailto:[email protected][email protected]&subject=Greetings%20from%20Cupertino!&body=Wish%20you%20were%20here!

For detailed information on the format of the mailtoscheme, seeRFC 2368.

iOS Note: If the Mail app is not installed, clicking amailtoURL displays an appropriate warning

message to the user.


6

Mail Links
http://www.ietf.org/rfc/rfc2368.txthttp://www.ietf.org/rfc/rfc2368.txt


7/16

Note: Phone links are supported on iOS only.

The tel URL scheme is used to launch the Phone app on iOS devices and initiate dialing of the specified phone

number. When a user taps a telephone link in a webpage, iOS displays an alert asking if the user really wants

to dial the phone number and initiates dialing if the user accepts. When a user opens a URL with the tel

scheme in a native app, iOS does not display an alert and initiates dialing without further prompting the user.

However, a native app can be configured to display its own alert.

You can specifyphone links explicitly in both web and native iOS apps using the tel URL scheme. The following

examples show the strings formatted for Safari and for a native app:

HTML link:

1-408-555-5555


tel:1-408-555-5555

To prevent users from maliciously redirecting phone calls or changing the behavior of a phone or account, the

Phone app supports most, but not all, of the special characters in the tel scheme. Specifically, if a URL contains

the*or#characters, the Phone app does not attempt to dial the corresponding phone number. If your app

receives URL strings from the user or an unknown source, youshould also make sure that any special characters

that might not be appropriate in a URL are escaped properly. For native apps, use the

stringByAddingPercentEscapesUsingEncoding: method ofNSStringto escape characters, which

returns a properly escaped version of your original string.

In Safari on iOS, telephone number detection is on by default. However, if your webpage contains numbers

that can be interpreted as phone numbers, but are not phone numbers, you can turn off telephone number

detection. You might also turn off telephone number detection to prevent the DOM document from being

modified when parsed by the browser. To turn off telephone number detection in Safari on iOS, use the

format-detectionmeta tag as follows:


7

Phone Links


8/16

Listing 2-1 shows a simple webpage in which automatic telephone number detection is off. When displayed

in Safari on iOS, the408-555-5555telephone number does not appear as a link. However, the1-408-555-5555number does appear as a link because it is in a phone link.

Listing 2-1 Turning telephone number detection off

Telephone Number Detection

A phone number: 1-408-555-5555

Not a phone number: 408-555-5555

iOS Note: If the Phone app is not installed on the iOS device, opening a telURL displays an

appropriate warning message to the user.

For more information about thetelURL scheme, seeRFC 2806andRFC 2396.

Phone Links


8
http://www.ietf.org/rfc/rfc2806.txthttp://www.ietf.org/rfc/rfc2396.txthttp://www.ietf.org/rfc/rfc2396.txthttp://www.ietf.org/rfc/rfc2806.txt


9/16

ThefacetimeURL scheme is used to launch the FaceTime app and initiate a call to the specified user. You

can use the phone number or email address of a user to initiate the call. When a user taps a FaceTime link in

a webpage, iOS confirms that the user really wants to initiate a FaceTime call before proceeding. When an app

opens a URL with the facetime scheme, iOS opens the FaceTime app and initiate the call without prompting

the user. When opening FaceTime URLs on OS X, the system always prompts the user before initiating a call.

You can specify FaceTime links explicitly in both web and native iOS apps using the facetimeURL scheme.

The following examples show the strings formatted for Safari and for a native app:

HTML link:

Connect using FaceTime

Connect using FaceTime


// 14085551234facetime:

facetime://[email protected]

To prevent users from maliciously redirecting calls or changing thebehavior of a phone or account, theFaceTime

app supports most, but not all, of the special characters in the facetime scheme. Specifically, if a URL contains

the * or #characters, the app ignores those characters when they are included after thephone number. If your

app receives URL strings from the user or from an unknown source, use the

stringByAddingPercentEscapesUsingEncoding: methodofNSString to generate a properly escaped

version of the original string before opening the URL.

iOS Note: If the FaceTime app is not installed on the iOS device or OS X computer, opening a

facetimeURL displays an appropriate warning message to the user. Prior to iOS 7, the Phone app

handles FaceTime calls.


9

FaceTime Links


10/16

Note: SMS text links are supported on iOS only.

Thesmsscheme is used to launch the Messages app. The format for URLs of this type is sms:,

whereis an optional parameter that specifies the target phone number of the SMS message. This

parameter can contain the digits 0 through 9 and the plus (+), hyphen (-), and period (.) characters. The URL

string must not include any message text or other information.

The following examples show strings formatted for Safari and for native apps. HTML links:

Launch Messages App

New SMS Message

Native app URL strings:

sms:

sms:1-408-555-1212


10

SMS Links


11/16

The maps URL scheme is used to show geographical locations and to generate driving directions between two

points. If your app includes address or location information, you can use map links to forward that information

to the Maps app on iOS or OS X.

Unlike some schemes, map URLs do not start with a maps scheme identifier. Instead, map links are specified

as regularhttplinks and are opened either in Safari or the Maps app on the target platform. The following

examples show the strings you would use in Safari and in a native app to show a map of the city of Cupertino,

California in the Maps app.

HTML link:

Cupertino


http://maps.apple.com/?q=cupertino

The following examples show the strings you would use to provide driving directions between San Francisco

and Cupertino:

HTML link:

Directions

Native app string:

http://maps.apple.com/?daddr=San+Francisco,+CA&saddr=cupertino


11

Map Links


12/16

URLs that contain no path parameters or that contain specific map paths are opened in Safari and displayed

there. For example,URLs basedonthepathshttp://maps.apple.com/ , http://maps.apple.com/maps ,

http://maps.apple.com/local , and http://maps.apple.com/mare all opened in Safari. To open a

URL in the Maps app, the path must be of the form http://maps.apple.com/?q.

The rules for creating a valid map link are as follows:

The domain must be maps.apple.com.

The path cannot be/maps/*.

A parameter cannot beq=*if the value is a URL (so KML is not picked up).

The parameters cannot includeview=textordirflg=r.

Table 5-1 lists the supported parameters along with a brief description of each.

Table 5-1 Supported Apple Maps parameters

NotesParameter

The query parameter. This parameter is treated as if it had been typed into the query

box by the user in the Maps app. q=*is not supported

q=

The location part of the query.near=

The latitude and longitude points (in decimal format, comma separated, and in that

order) for the map center point.

ll=

The latitude and longitude points from which a business search should be performed.sll=

The approximate latitude and longitude span.spn=

A custom latitude and longitude span format used by Apple. The value of this parameter

is the latitude and longitude separated by a comma. For example, to specify a latitudinal

span of 20.4 degrees and a longitudinal span of 30.8 degrees, you would use the string

sspn=20.4,30.8.

sspn=

The type of map to display.t=

The zoom level.z=

The source address, which is used when generating driving directionssaddr=

The destination address, which is used when generating driving directions.daddr=

Map Links


12


13/16

The iTunes URL scheme is used to link to content on the iTunes Music Store. The iTunes URL format is

complicated to construct, so you create it using an online tool called iTunes Link Maker. The tool allows you

to select a country destination and media type, and then search by song, album, or artist. After you select the

item you want to link to, it generates the corresponding URL.

The following examples show the strings you would use in Safari and in a native iOS app to link to a song on

the iTunes Music Store. The HTML example includes the complete link returned by the iTunes Link Maker tool,

which includes a link to any appropriate artwork for the target link.

HTML link:


http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?i=156093464&id=156093462&s=143441

For more information on creating iTunes links, seeiTunes Link Maker FAQ. That webpage contains a link to

the iTunes Link Maker tool.


13

iTunes Links
http://www.apple.com/itunes/linkmaker/faq/http://www.apple.com/itunes/linkmaker/faq/


14/16

The YouTube URL scheme is used to connect to the YouTube website to play the specified video. If your app

links to YouTube content, you can use this scheme to play videos from your app.

Unlike some schemes, YouTubeURLs do notstart with a youtube schemeidentifier. Instead, they arespecified

as regularhttplinks but are targeted at the YouTube server. The following examples show the basic strings

you would use in Safari and in an app to show a YouTube video. In each example, you would need to replace

the VIDEO_IDENTIFIERvalue with the identifier of the video you wanted to display:

HTML links:

Play Video

Play Video

Native app URL strings:

http://www.youtube.com/watch?v=VIDEO_IDENTIFIER

http://www.youtube.com/v/VIDEO_IDENTIFIER

iOS Note: If the YouTube video cannot be viewedon the device, iOSdisplays an appropriate warning

message to the user.


14

YouTube Links


15/16

This table describes the changes toApple URL Scheme Reference .

NotesDate

OS X now supports map links.2013-09-18

Updated information about the usage of the maps URL scheme.2012-12-13

Changed the map-related URL information to reflect Apple map support.2012-09-19

Applied minor edits.2010-12-15

Minor edits throughout.2009-06-17

Updated the description of the mailto scheme to reflect the fact that iOS

ignores the from attribute.

2009-06-08

Changed the title from "iPhone URLScheme Reference" and appliedother

minor edits throughout.

2009-01-06

Added information about support for the sms URL scheme.2008-10-29

First version of iPhone URL Scheme Reference.2008-10-15

The information in this document was previously published iniOS

Programming Guide .


15

Document Revision History


16/16

Apple Inc.

Copyright 2013 Apple Inc.

All rights reserved.

No part of this publication may be reproduced,

storedin a retrievalsystem, or transmitted, in any

form or by any means, mechanical, electronic,photocopying, recording, or otherwise, without

prior written permission of Apple Inc., with the

following exceptions: Any person is herebyauthorized to store documentation on a single

computer or device for personal use only and to

print copies of documentation for personal useprovided that the documentation contains

Apples copyright notice.

No licenses, express or implied, are granted with

respect to anyof thetechnology describedin this

document. Apple retains all intellectual propertyrights associated with the technology described

in this document. This document is intended to

assist application developers to develop

applications only for Apple-branded products.

Apple Inc.1 Infinite Loop

Cupertino, CA 95014

408-996-1010

Apple, the Apple logo, Cocoa, Cocoa Touch,

FaceTime, iPhone, iTunes, Mac, OS X, Safari, and

WebObjects are trademarks of Apple Inc.,registered in the U.S. and other countries.

iTunes Music Store is a servicemark of Apple Inc.,

registered in the U.S. and other countries.

IOS is a trademark or registered trademark of

Cisco in the U.S. and other countries and is used

under license.APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT,THIS DOCUMENT IS PROVIDEDAS IS, AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL,INCIDENTAL,OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT, ERROR ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

Some jurisdictions do not allow the exclusion ofimplied warranties or liability,so the aboveexclusionmay not apply to you.

Documents

IPhoneURLScheme Reference ios