Deep-linking into an app

What we’ll be able to do when we’re done

When you’re done with this tutorial, your demo application will be able to respond to two different URLs: birdland://home and birdland://about, which will take you to the “home” and “about” sections of the app, respectively.

Why you need this in your application

With Twitter Cards, a piece of content can be deep-linked to a specific section of your application. This functionality is incredibly powerful, as it can drive engagement for users who already have your application installed. For users who do not have your application, a link to the App Store is shown so they can easily download it.

How to implement

Step 0 - Complete the previous tutorial

In the previous tutorial, you add a custom URL scheme, birdland://, to an iOS application. This tutorial builds upon the result of that step, so make sure that you’ve completed it before continuing here.

Step 2 - Add support for URL routing

Open the project that you created in the previous tutorial. Next, open the implementation file for the UIApplicationDelegate for the app, “AppDelegate.m”. We’re going to add a new method, openURL, that will handle URLs that are opened by our application.

-(BOOL) application: (UIApplication * ) application openURL: (NSURL * ) url sourceApplication: (NSString * ) sourceApplication annotation: (id) annotation {
    if ([url.scheme isEqualToString: @"birdland"]) {
        // check our `host` value to see what screen to display
        //TODO you can also pass parameters - e.g. birdland://home?refer=twitter
        if ([ isEqualToString: @"home"]) {
            [self.viewController presentHomeScreen];
        } else if ([ isEqualToString: @"about"]) {
            [self.viewController presentAboutScreen];
        } else {
            NSLog(@"An unknown action was passed.");
    } else {
        NSLog(@"We were not opened with birdland.");
    return NO;

Step 3 - Implement our UI

Next, we to add our two simple methods to our View Controller. Open ViewController.m and add the following:

#import "ViewController.h"

#define THE_CREATOR @"Your-handle-here!"

@interface ViewController()

@property(nonatomic, strong) UILabel * viewLabel;


@implementation ViewController - (void) viewDidLoad {
    [super viewDidLoad];
    self.viewLabel = [
        [UILabel alloc] initWithFrame: self.view.frame
    self.viewLabel.textAlignment = NSTextAlignmentCenter;
    [self.view addSubview: self.viewLabel];
    [self presentHomeScreen];
} - (void) presentHomeScreen {
    NSLog(@"'Presenting' the home screen.");
    self.viewLabel.text = @"Welcome home!";
} - (void) presentAboutScreen {
    NSLog(@"'Presenting' the about screen");
    self.viewLabel.text = [NSString stringWithFormat: @"About: created by %s", THE_CREATOR];
} - (void) didReceiveMemoryWarning {
    [super didReceiveMemoryWarning];


You’re doing all the hard work here, so update the value defined for THE_CREATOR to be your Twitter handle.

Step 4 - Update our View Controller’s interface

Now, let’s update our View Controller’s interface file, ViewController.h, and make it look like this:

#import <UIKit/UIKit.h>

@interface ViewController : UIViewController

- (void)presentHomeScreen;
- (void)presentAboutScreen;


Verify that everything works

First, build and run the application to make sure that everything compiles properly. You should see a screen like the following:


Now, to check that our registered URL scheme works, we’ll head out to mobile Safari. Press the “Home” button in the Simulator (or press command-shift-H) to reach the Home Screen. Open Safari.

Next, type “birdland://about” in the address bar of Safari. Press Go. You should see our about section:


Apply this tutorial to your application

To apply this tutorial to your application, you’ll first need decide where you users to be able to deep-link into your application. Some simple questions to get you started:

  • How does the user navigate in your app?
  • How does the user view a single piece of content in your app?
  • Are there are specific sections that you would want to direct users to?
  • Finally, if a user shares a piece of content to another user, what’s the experience you want the second user to receive?

The actual technique that you use in your app may be much more complex than what we cover here, but the overall approach will be the same.