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 10.3 and later displays an alert and requires user confirmation before dialing. (When this scenario occurs in versions of iOS prior to 10.3, iOS initiates dialing without further prompting the user and does not display an alert, although a native app can be configured to display its own alert.)
FaceTime in macOS 10.10 and later can also use the tel URL scheme to launch the Phone app on an iOS device by using Handoff. This scenario works when FaceTime is configured to dial phone numbers (the default configuration) and the iOS device is connected to the same iCloud account as the Mac.
You can specify phone 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:
Native app URL string:
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, you should 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 of NSString to 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-detection meta tag as follows:
Listing 2-1 shows a simple webpage in which automatic telephone number detection is off. When displayed in Safari on iOS, the 408-555-5555 telephone number does not appear as a link. However, the 1-408-555-5555 number does appear as a link because it is in a phone link.
Listing 2-1 Turning telephone number detection off
iOS Note: If the Phone app is not installed on the iOS device, opening a tel URL displays an appropriate warning message to the user.
For more information about the tel URL scheme, see RFC 2806 and RFC 2396 .
This document describes several URL schemes that are supported by system apps on iOS, OS X, and watchOS 2 and later. 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 iOS app displays telephone numbers, 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 app and plays the song specified in the link. When a user clicks a link, what happens 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 schemes supported on different Apple platforms.
At a Glance
You 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 code—using the openURL: method of the shared UIApplication object to open URLs—and HTML samples. For more information on how to use the openURL: method, see UIApplication Class Reference.
Composing Items Using Mail
Use the mailto scheme to open the Mail app and populate a new email with information.
Relevant Chapter: Mail Links
Starting a Phone or FaceTime Conversation
Use the tel and facetime schemes to initiate telephone or video conversations.
Specifying Text Messages
Use the sms scheme to compose a text message and specify a recipient.
Relevant Chapter: SMS Links
Opening Locations in Maps
Use specially formatted URLs to open the Maps app and display directions or locations.
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 open that information in the Maps app in iOS or macOS.
Unlike some schemes, map URLs do not start with a “maps” scheme identifier. Instead, map links are specified as regular http links and are opened either in Safari or the Maps app on the target platform.
Table 5-1 lists the supported parameters along with a brief description of each.
Table 5-1 Supported Apple Maps parameters
The map type. If you don’t specify one of the documented values, the current map type is used.
m (standard view)
k (satellite view)
The query. This parameter is treated as if its value had been typed into the Maps search field by the user. Note that q=* is not supported
The q parameter can also be used as a label if the location is explicitly defined in the ll or address parameters.
A URL-encoded string that describes the search object, such as “pizza,” or an address to be geocoded
The address. Using the address parameter simply displays the specified location, it does not perform a search for the location.
An address string that geolocation can understand.
A hint used during search. If the sll parameter is missing or its value is incomplete, the value of near is used instead.
A comma-separated pair of floating point values that represent latitude and longitude (in that order).
The location around which the map should be centered.
The ll parameter can also represent a pin location when you use the q parameter to specify a name.
A comma-separated pair of floating point values that represent latitude and longitude (in that order).
The zoom level. You can use the z parameter only when you also use the ll parameter; in particular, you can’t use z in combination with the spn or sspn parameters.
A floating point value between 2 and 21 that defines the area around the center point that should be displayed.
The area around the center point, or span. The center point is specified by the ll parameter.
You can’t use the spn parameter in combination with the z parameter.
A coordinate span (see MKCoordinateSpan ) denoting a latitudinal delta and a longitudinal delta.
The source address to be used as the starting point for directions.
A complete directions request includes the saddr , daddr , and dirflg parameters, but only the daddr parameter is required. If you don’t specify a value for saddr , the starting point is “here.”
An address string that geolocation can understand.
The destination address to be used as the destination point for directions.
A complete directions request includes the saddr , daddr , and dirflg parameters, but only the daddr parameter is required.
An address string that geolocation can understand.
The transport type.
A complete directions request includes the saddr , daddr , and dirflg parameters, but only the daddr parameter is required. If you don’t specify one of the documented transport type values, the dirflg parameter is ignored; if you don’t specify any value, Maps uses the user’s preferred transport type or the previous setting.
r (by public transit)
The search location. You can specify the sll parameter by itself or in combination with the q parameter. For example, http://maps.apple.com/?sll=50.894967,4.341626&z=10&t=s is a valid query.
A comma-separated pair of floating point values that represent latitude and longitude (in that order).
The screen span. Use the sspn parameter to specify a span around the search location specified by the sll parameter.
A coordinate span (see MKCoordinateSpan ) denoting a latitudinal delta and a longitudinal delta.
You can use the maps URL scheme to help the user:
Perform a search
Get directions to a location
View a specific location
To perform a search, supply a properly encoded URL string as the value of the q parameter. For example:
To specify a location for search, you can supply a value for the near parameter, or combine the sll parameter with either the z or sspn parameters. You can also set the map type using the t parameter, as shown here:
To provide navigation directions from one location to another, supply the start and destination addresses in the saddr and daddr parameters as shown below. You can also supply much more detail for the start and destination addresses than is shown here.
To specify a transport type, you can use the dirflg parameter as shown here:
You can omit the start address when you want to provide directions “from here.” The following example shows a search from here that provides driving directions in a hybrid map.
To display a specific location, use the ll parameter to center the map at the specified position as shown here:
Another way to display a location is to specify an address, such as:
If you use both the ll and address parameters, ll takes precedence over address . If you include a name in the value of the q parameter, Maps tries to match the name at the specified location.
The URL scheme is an interesting feature provided by the iOS SDK that allows developers to launch system apps and third-party apps through URLs. For example, let’s say your app displays a phone number, and you want to make a call whenever a user taps that number. You can use a specific URL scheme to launch the built-in phone app and dial the number automatically. Similarly, you can use another URL scheme to launch the Message app for sending an SMS. Additionally, you can create a custom URL scheme for your own app so that other applications can launch your app via a URL. You’ll see what I mean in a minute.
As usual, we will build an app to demonstrate the use of URL schemes. We will reuse the QR code reader app that was built in the previous chapter. If you haven’t read the QR code tutorial, go back and read it before continuing on.
So far, the demo app is capable of decoding a QR code and displaying the decoded message on screen. In this chapter, we’ll make it even better. When the QR code is decoded, the app will launch the corresponding app based on the type of the URL.
To start with, first download the QRCodeReader app. If you compile and run the app, you’ll have a simple QR code reader app. Note that the app only works on a real iOS device.
Sample QR Codes
Here I include some sample QR codes that you can use to test the app. Alternatively, you can create your QR code using online services like www.qrcode-monkey.com. Open the demo app and point your device’s camera at one of the codes. You should see the decoded message.
Using URL Schemes
For most of the built-in applications, Apple provides support for URL schemes. For instance, you use the mailto scheme to open the Mail app (e.g. mailto:[email protected] ) or the tel scheme to initiate a phone call (e.g. tel://743234028 ). To open an application with a custom URL scheme, all you need to do is call the open(_:options:completionHandler:) method of the UIApplication class. Here is the line of code:
Now, we will modify the demo app to open the corresponding app when a QR code is decoded. Open the Xcode project and select the QRScannerController.swift file. Add a helper method called launchApp in the class:
The launchApp method takes in a URL decoded from the QR code and creates an alert prompt. If the user taps the Confirm button, the app then creates an URL object and opens it accordingly. iOS will then open the corresponding app based on the given URL.
In the metadataOutput method, which is called when a QR code is detected, insert a line of code to call the launchApp method:
Place the above line of code right after:
Now compile and run the app. Point your device’s camera at one of the sample QR codes (e.g. tel://743234028 ). The app will prompt you with an action sheet when the QR code is decoded. Once you tap the Confirm button, it opens the Phone app and initiates the call.
But there is a minor issue with the current app. If you look into the console, you should find the following warning:
The launchApp method is called every time when a barcode or QR code is scanned. So the app may present another UIAlertController when there is already a UIAlertController presented. To resolve the issue, we have to check if the app has presented a UIAlertController object before calling the present(_:animated:completion:) method.
In iOS, when you present a view controller modally using the present(_:animated:completion:) method, the presented view controller is stored in the presentedViewController property of the current view controller. For example, when the QRScannerController object calls the present(_:animated:completion:) method to present the UIAlertController object, the presentedViewController property is set to the UIAlertController object. When the UIAlertController object is dismissed, the presentedViewController property will be set to nil .
With this property, it is quite easy for us to fix the warning issue. All you need to do is to put the following code at the beginning of the launchApp method:
We simply check if the property is set to a specific view controller, and present the UIAlertController object only if there is no presented view controller. Now run the app again. The warning should go away.
One thing you may notice is that the app cannot open these two URLs:
These URLs are known as custom URL schemes created by third-party apps. For iOS 9 and later, the app is not able to open these custom URLs. Apple has made a small change to the handling of URL scheme, specifically for the canOpenURL() method. If the URL scheme is not registered in the whitelist, the method returns false . If you refer to the console messages, you should see the error like this:
This explains why the app cannot open Facebook and Whatsapp even it can decode their URLs. We will discuss more about custom URL scheme in the next section and show you how to workaround this issue.
Creating Your Custom URL Scheme
In the sample QR codes, I included two QR codes from third party apps:
Facebook – fb://feed
Whatsapp – whatsapp://send?text=Hello!
The first URL is used to open the news feed of the user’s Facebook app. The other URL is for sending a text message using Whatsapp. Interestingly, Apple allows developers to create their own URLs for communicating between apps. Let’s see how we can add a custom URL to our QR Reader app.
We’re going to create another app called TextReader. This app serves as a receiver app that defines a custom URL and accepts a text message from other apps. The custom URL will look like this:
When an app (e.g. QR Code Reader) launches the URL, iOS will open the TextReader app and pass it the Hello! message. In Xcode, create a new project using the Single View Application template and name it TextReader . Once the project is created, expand the Supporting Files folder in the project navigator and select Info.plist . Right click any blank areaU and select Add Row to create a new key.
You’ll be prompted to select a key from a drop-down menu. Scroll to the bottom and select URL types . This creates an array item. You can further click the disclosure icon (i.e. triangle) to expand it. Next, select Item 0 . Click the disclosure icon next to the item and expand it to show the URL identifier line. Double-click the value field to fill in your identifier. Typically, you set the value to be the same as the bundle ID (e.g. com.appcoda.TextReader).
Next, right click on Item 0 and select Add Row from the context menu. In the dropdown menu, select URL Schemes to add the item.
Again, click the disclosure icon of URL Schemes to expand the item. Double click the value box of Item 0 and key in textreader . If you’ve followed the procedures correctly, your URL types settings should look like this:
That’s it. We have configured a custom URL scheme in the TextReader app. Now the app accepts the URL in the form of textreader:// . We still need to write a few lines of code such that it knows what to do when another app launches the custom URL (e.g. textreader://Hello! ).
As you know, the AppDelegate class implements the UIApplicationDelegate protocol. The method defined in the protocol gives you a chance to interact with important events during the lifetime of your app.
If there is a Open a URL event sent to your app, the system calls the application(_:open:options:) method of the app delegate. Therefore, you’ll need to implement the method in order to respond to the launch of the custom URL.
Open AppDelegate.swift and insert the following code to implement the method:
From the arguments of the application(_:open:options:) method, you can get the URL resource to open. For instance, if another app launches textreader://Hello! , then the URL will be embedded in the URL object. The first line of code extracts the message by using the host property of the URL structure.
URLs can only contain ASCII characters, spaces are not allowed. For characters outside the ASCII character set, they should be encoded using URL encoding. URL encoding replaces unsafe ASCII characters with a % followed by two hexadecimal digits and a space with %20 . For example, “Hello World!” is encoded to Hello%20World! The removingPercentEncoding method is used to decode the message by removing the URL percent encoding. The rest of the code is very straightforward. We instantiate a UIAlertController and present the message on screen.
If you compile and run the app, you should see a blank screen. That’s normal because the TextReader app is triggered by another app using the custom URL. You have two ways to test the app. You can open mobile Safari and enter textreader://Great!%20It%20works! in the address bar – you’ll be prompted to open the TextReader app. Once confirmed, the system should redirect you to the TextReader app and displays the Great! It works! message.
Alternatively, you can use the QR Code Reader app for testing. If you open the app and point the camera to the QR code shown below, the app should be able to decode the message but fails to open the TextReader app.
The console should show you the following error:
As explained earlier, Apple has made some changes to the canOpenURL method since iOS 9. You have to register the custom URL schemes before the method returns true . To register a custom scheme, open Info.plist of the QRReaderDemo project and add a new key named LSApplicationQueriesSchemes . Set the type to Array and add the following items:
Once you’ve made the change, test the QR Reader app again. Point to a QR code with a custom URL scheme (e.g. textreader). The app should be able to launch the corresponding app.
Furthermore, if you scan the QR code of the Facebook scheme or Whatsapp scheme, the app should now be able to launch the Facebook/Whatsapp app accordingly.
