Posted on by

Step 1: build.settings

The first thing you need to do is register your app URL schemes by adding a table to build.settings. Here’s an example build.settings file with two different URL schemes (one for Facebook, and another one):


settings = {
orientation = {
default = { "portrait" }
},

iphone = {
plist = {
UIApplicationExitsOnSuspend = false,
CFBundleURLTypes =
{
{
CFBundleURLSchemes =
{
"fb1234567890", -- example scheme for facebook
"coronasdkapp", -- example second scheme
}
}
}
}
}
}

As you can see from the example above, you can have multiple URL schemes for a single app. If your app has a URL scheme that’s the same as an URL scheme assigned to another app on the device, then iOS will present the user with an option to choose which app they want to launch.

With the above build.settings, users will be able to launch your app by navigating to:

  • fb1234567890://
  • coronasdkapp://

The following URLs are also valid (with the example build.settings):

  • fb1234567890://randomvalue
  • coronasdkapp://anythingyouwant

And once again, your apps with registered URL schemes can be launched from anywhere that accepts opening URLs, such as Mobile Safari (which is a great way to test your URL schemes).

Step 2: Getting the URL String

Being able to open/launch an app using an URL scheme is great, but what’s even better is being able to tell your app to do something in response to being opened via a URL scheme.

When your app is opened with the URL scheme, your app is passed the entire URL string that was called, not just the string you registered. For example, let’s say you register an url scheme of “coronasdkapp” for your app. If the user navigates to: coronasdkapp://testparameter, then your app will receive: “coronasdkapp://testparameter” through your listener.

Think for a moment just how powerful this can be. You could tell your app to do different things, or start in a different state depending on the URL string that was used to launch your app! Your creative juices should be flowing by now. :-)

Cold Launches

A “cold launch” is when your app is neither in the foreground, nor is it suspended; it is completely closed. If your app is launched using a URL scheme, then here is how you would get the URL string that was used to launch your app:

main.lua

local launchArgs = ...

local launchURL
if launchArgs and launchArgs.url then
launchURL = launchArgs.url
end

print( launchURL ) -- output: coronasdkapp://mycustomstring

The example above assumes your app has “coronasdkapp” registered as a URL scheme, and that the user launched the app using the following URL string: coronasdkapp://mycustomstring

In the example above, if the user launches the app normally (not with an url scheme), then the value of launchURL will be nil.

Suspended Apps

If your app is already opened but not in the foreground, it is considered “suspended”. When your app is launched with a URL scheme while it is suspended, you can get the URL used to launch your app using a System Event Listener. Here’s an example:

main.lua

local launchURL

local function onSystemEvent( event )
if event.type == "applicationOpen" and event.url then
launchURL = event.url
print( launchURL ) -- output: coronasdkapp://mycustomstring
end
end

Runtime:addEventListener( "system", onSystemEvent )

Remember, your app will only receive the “applicationOpen” event.type as a system event if your app was opened using the URL scheme while your app is currently suspended.

Handling Both

You could simply combine the two examples above and everything would be just fine, but I recommend putting your code in a function, and just calling the function from the two different places. Here’s an example of how you could do that:


local launchArgs = ...

local function printURL( url )
print( url ) -- output: coronasdkapp://mycustomstring
end

if launchArgs and launchArgs.url then
printURL( launchArgs.url )
end

local function onSystemEvent( event )
if event.type == "applicationOpen" and event.url then
printURL( event.url )
end
end

Runtime:addEventListener( "system", onSystemEvent )

 

Available Through Daily Builds

Remember, this amazingly useful feature is only available to subscribers via Daily Builds, so if you’re not a subscriber yet, subscribe now so you can get the latest build with this, and other great features such as Push Notifications, Email/SMS sending (w/ attachments), and more!


Posted by . Thanks for reading...

12 Responses to “Using App URL Schemes in iOS”

  1. T. Chuin

    Is there an equivalent of the canOpenURL, which return a BOOL true/false if there is a handler registered for a particular url type?

    Reply
  2. OnTouch

    JB, this will work to link gamecenter leaderboard?. I think is based also on this scheme.

    Also, can work with app-store direct link ? Thanks.

    Reply
  3. Marc

    Hi Jonathan, please find a way to store all the informations that you provide on the blog somewhere else in the documentation.
    It has become very hard to follow the updates that way.

    We need better docs. Really. Searching on the blog or the forums to find informations has become tiresome and counter productive.

    Thank you for the blog posts though. I just feel that it’s a waste of time if those valuable informations are lost in the blog archives soon.

    Reply
  4. J

    applicationOpen event not firing: I am currently implementing Facebook deep linking in my app using a URL scheme. I’ve gotten everything to work from a cold start (i.e. not from suspended state): I click on open graph object in my Facebook news feed and it takes me directly to the object in the app.

    However, I can’t get this functionality working when the app resumes from a suspended state. The link still opens my app, but only an applicationResume event fires, not an applicationOpen event; and since there’s no corresponding event.url for the applicationResume event, there’s no data for me to parse and direct the user to the requested page.

    https://developer.coronalabs.com/forum/2012/08/08/applicationopen-event-not-firing

    Reply
  5. Jose

    I’m very interested in this feature to be ported to Android or something similar, there is any way to open an App from the actual in Android? Could I send parameters when I open it?

    Any help will be welcome! Thanks in advance.

    Reply
  6. Richard Harris

    We need this working on Android, it’s a fundamental part of any app and should be considered a priority over some other smaller daily add-ons in the builds.

    Reply

Leave a Reply

  • (Will Not Be Published)