Using App URL Schemes in iOS

Share on Facebook0Share on Google+4Tweet about this on TwitterShare on LinkedIn0

iOS Url Scheme in Corona SDKHave you ever wondered how apps get launched from other apps, whether it’s a link you touched in Mobile Safari, or a button you pressed in another app? Well today, I’m going to show you how to do exactly that with one of the new features that recently came out in the Daily Builds.

The technical term is “app URL schemes” and I already touched on how to do it (indirectly) during last week’s tutorial on how to upload photos using the Facebook API. That’s because Facebook single sign-on cleverly makes use of an app URL scheme to bring the user back to your app after authenticating.

Note to Android Developers

App URL schemes, which are accomplished via “intent filters” on Android, are implemented much differently than they are on iOS, so this tutorial applies to iOS developers only. As soon as we have intents on Android ready to go, there will be a corresponding tutorial shortly after.

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:


local launchArgs = ...

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

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:


local launchURL

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

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

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

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

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!

Share on Facebook0Share on Google+4Tweet about this on TwitterShare on LinkedIn0

This entry has 14 replies

  1. T. Chuin says:

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

  2. OnTouch says:

    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.

  3. ojnab says:

    Wow ansca all the new 707 features are so sweet. Best christmas present this year!

  4. Marc says:

    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.

  5. Bernardo says:

    @Marc, I second that. It is very tiresome..

  6. Blanco says:

    When is this function going to work for android?

  7. J says:

    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.

  8. Jose says:

    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.

  9. 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.

  10. Kay says:

    Any progress making this active on Android?

  11. Darren says:

    Can I know any update on making Corona open other application on Android platform? It’s been a while…

  12. Martin says:

    Does this work on Android?

  13. Renato - Red Beach says:

    For Android URL scheme, read Joshua post here: