Shortcut for iOS

This SDK provides the following features:

  • Collection of statistics (app usage, deep links).
  • Support for deferred deep linking.
  • Creation Shortcuts (short mobile deep links) to share from within your app.

There is also an Android version of this SDK.

Requirements

The SDK works with any device running iOS6 and newer.

Installation

You can install the SDK either using CocoaPods or by integrating it as a .framework file into your app.

Using CocoaPods
  1. Add pod 'Shortcut' to your Podfile.
  2. Run pod install.
Integrating the .framework file
  1. Download the latest SDK as zip file from the releases page.
  2. Unzip it and add the Shortcut.framework file to your project, e.g. by dragging it into the Project Navigator of your project in Xcode.
  3. Within your project's Build phases make sure that the Shortcut.framework is added in the Link binary with libraries section. If you don't find it there, drag it from the Project Navigator to the list.

Prerequisites

To make use of this SDK you need the following:

  • An API key. Use the Shortcut Manager to create a mobile app with an associated API key.

For the deep linking features you need in addition:

Integration into your app

General setup

Make sure to import our SDK in all files where you use it:

#import <Shortcut/Shortcut.h>

Use the Shortcut Manager to create a mobile app with an associated API key. Then launch the SDK with your API key's auth token by adding the following to -application:didFinishLaunchingWithOptions: in your AppDelegate.m file:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [Shortcut launchWithAuthToken:@"YOUR_AUTH_TOKEN_HERE"];

    // ...
    return YES;
}

Collecting deep link interaction statistics

To collect deep link interaction statistics you have to tell the SDK when a deep link is opened: The SDK keeps track of your users looking at deep link content through sessions. You have to create a session whenever a a deep link is opened; the SDK will automatically terminate the session when a user leaves your app.

When using custom URL schemes:

Add the following to -application:openURL:sourceApplication:annotation: (you have added this method to your app delegate when you implemented your app's custom-scheme deep link handling):

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {

    SCSession *deepLinkSession = [Shortcut startDeepLinkSessionWithURL:url];
    url = deepLinkSession.url; // Use the session object's url property for further processing

    // ...
}
When using Universal Links:

Add the following to -application:continueUserActivity:restorationHandler: (you have added this method to your app delegate when you implemented your app's Universal Link handling):

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {

    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        self.deepLinkSession = [Shortcut startDeepLinkSessionWithURL:userActivity.webpageURL];
        userActivity.webpageURL = self.deepLinkSession.url; // Use the session object's url property for further processing
    }

    // ...
}

Creating Shortcuts (short mobile deep links)

Shortcut allows you to generate short links immediately, no (potentially slow) backend roundtrip is required. This works as follows:

  1. The SDK generates a unique short link and returns it to you immediately
  2. The generated short link as well as all its parameters (website URL, title, deep links) are sent to the Shortcut backend in the background

This way you get a link immediately that you can present in a share sheet or send out via email, no need to wait for a backend.

Important: You must make sure that a network connection is available when calling this method!

An example: Let's assume you have a Share button in your app which should bring up an action sheet that allows you to share some content within your app through a short link.

An implementation could look something like this:

- (IBAction)shareButtonPressed:(id)button {

    NSURL *shortLinkURL = [Shortcut createShortLinkWithTitle:@"content title"
                                                  websiteURL:[NSURL URLWithString:@"http://your.site/content"]
                                                    deepLink:[NSURL URLWithString:@"your-app://your/content"]];
    [self displayShareSheetWithURL:shortLinkURL];
}

- (void)displayShareSheetWithURL:(NSURL *)urlToShare {
    // ...
}
Alternative: Asynchronous creation

There is also an asynchronous way to create a new short link. It works as follows:

  1. The SDK sends the parameters for the short link to the backend
  2. The backend generates a new short link and returns it to the SDK
  3. The SDK notifies you of the new short link via a completion handler

This way you have to wait for the backend to generate the short link, but if there are any errors (e.g. no network connection) then you can react to them.

The implementation of the example above would look like this with the asynchronous call:

 - (IBAction)shareButtonPressed:(id)button {

    [Shortcut createShortLinkWithTitle:@"content title"
                            websiteURL:[NSURL URLWithString:@"http://your.site/content"]
                              deepLink:[NSURL URLWithString:@"your-app://your/content"]
                     completionHandler:^(NSURL *shortLinkURL, NSError *error) {
                         if (!error) {
                             [self displayShareSheetWithURL:shortLinkURL];
                         } else {
                             // do error handling...
                         }}];
}

- (void)displayShareSheetWithURL:(NSURL *)urlToShare {
    // ...
}
Different deep links per platform

If your deep links are not identical for the different platforms your app supports (iOS, Android, Windows Phone) then you can specify them on a per-platform basis, just use [Shortcut createShortLinkWithTitle:websiteURL:iOSDeepLink:androidDeepLink:windowsPhoneDeepLink:] / [Shortcut createShortLinkWithTitle:websiteURL:iOSDeepLink:androidDeepLink:windowsPhoneDeepLink:completionHandler:] instead.

Custom domain for short links

If you set up a custon domain for your short links in the Shortcut Manager and want to use it for short links created from the SDK as well, then you need to tell the SDK about it. This is done by launching the SDK with a custom domain parameter. Just replace the SDK launch call in -application:didFinishLaunchingWithOptions: in your AppDelegate.m file:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [Shortcut launchWithAuthToken:@"YOUR_AUTH_TOKEN_HERE" shortLinkDomain:@"YOUR_DOMAIN_HERE"]; // instead of: [Shortcut launchWithAuthToken:@"YOUR_AUTH_TOKEN_HERE"];

    // ...
    return YES;
}

Migrating from the Shortcut Deep Linking SDK

The Shortcut Deep Linking SDK has been deprecated and its functionality has been included into this SDK/Shortcut for iOS.

Please follow these steps to migrate your code to use this new SDK:

  1. Remove the ShortcutDeepLinkingSDK.framework from your project in Xcode.
  2. Follow the steps in the Installation and Prerequisites sections to add the new framework to your app.
  3. Replace all occurrences of #import <ShortcutDeepLinkingSDK/ShortcutDeepLinkingSDK.h> with #import <Shortcut/Shortcut.h>.
  4. This SDK uses class methods on the Shortcut class for all its interactions instead of instance methods on the singleton instance of the SCDeepLinking class. So you have to replace all of the following calls to the SDK in your code:
    • [[SCDeepLinking sharedInstance] launch] with [Shortcut launchWithAuthToken:]
    • [[SCDeepLinking sharedInstance] startSessionWithURL:] with [Shortcut startDeepLinkSessionWithURL:]
    • [[SCDeepLinking sharedInstance] createShortLinkWithTitle:websiteURL:deepLinkURL:completionHandler:] with [Shortcut createShortLinkWithTitle:websiteURL:deepLink:completionHandler:]
  5. Optional: Use the immediate short link generation from the new SDK if desired. Read through the Creating Shortcuts section above and replace calls to [Shortcut createShortLinkWithTitle:websiteURL:deepLink:completionHandler:] with [Shortcut createShortLinkWithTitle:websiteURL:deepLink:].

License

This project is released under the MIT license. See included LICENSE.txt file for details.

Shortcut SDK for Android

This SDK provides the following features:

  • Collection of statistics (app usage, deep links).
  • Support for deferred deep linking.
  • Shortcut creation (short mobile deep links) to share from within your app.

There is also an iOS version of this SDK.

Requirements

The SDK works with Android API 10+.

Installation

  1. Download the latest .AAR file from the releases page and copy it to the project's libs directory (typically app/libs).
  2. Add a directory repository in build.gradle and add compile 'sc.shortcut.sdk:shortcut-sdk:[email protected]' to the dependencies section of your application's build.gradle file.
repositories {
  flatDir {
    dirs 'libs'
  }
}
dependencies {
    compile 'sc.shortcut.sdk:shortcut-sdk:[email protected]'
}

If for some reason this installion method does not work, check out alternative installation methods.

Prerequisites

To make use of this SDK you need the following:

  • An API key. Use the Shortcut Manager to create a mobile app with an associated API key.

For the deep linking features you need in addition:

Integration into your app

Enabling the SDK

There are 4 methods to enable the SDK inside your app. The preferred method is Method 1: Register our Application class. If your application needs to support pre-14 API, please use Method 4: Manual session management.

Method 1: Register our Application class

Simply register our application class in the Manifest.xml configuration file and add your authentication token:

    <application
        android:name="sc.shortcut.sdk.SCApplication"
        ...>
        <meta-data android:name="sc.shortcut.sdk.authToken" android:value="<your auth token>" />

That's it! Your app supports now deferred deep linking and statistics are gathered automatically.

Method 2: Extend from our Application class

If you already have an Application class then extend it with SCApplication.

  public class YourApplication extends SCApplication

And add the authentication token to your Manifest.xml.

  <application>
    <meta-data android:name="sc.shortcut.sdk.authToken" android:value="<your key>" />
    ...

Method 3: Initialize the SDK yourself

We do not support this yet!

If you do not want to/can extend from SCApplication for some
reason you can initialize the SDK yourself in your
Application#onCreate() method or in the Activity receiving the
deep link intent.

  @Override
  public void onCreate() {
    super.onCreate();
    new SCApplication(this);
}

Method 4: Manual session management for pre-14 support

Unless you need to support API pre-14 we recommend using automatic session managment (methods 1 - 3).

In your entry Activity add the following:

  @Override
  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);

      SCConfig config = new SCConfig("<your auth token>");
      Shortcut shortcut = Shortcut.getInstance(config, this);    
      if (savedInstanceState == null) { // You wanna probably ignore device rotation
        shortcut.sendAppOpenEvent();

        // if app was opened with a deep link
        shortcut.startSession(getIntent());
      }
  }

Retrieve the deep link

Usually your app should respond to a deep link with a corresponding view. You can retrieve the deep link either from the incoming intent or from the Shortcut class.

Note that you can retrieve the deep link at any time during the activity's lifecyle, but generally you want to do so in onCreate() or onStart().

The following example shows how to retrieve the deep link through the incoming intent. If the app was launched for the first time a possible deferred link is available through the intent:

@Override
protected void onCreate(Bundle savedInstanceState) {
    ...

    if (Intent.ACTION_VIEW.equals(getIntent.getAction()) {
        Uri deepLink = getIntent().getData();
        if (deepLink != null) {
            Log.d(TAG, "opened with deep link: " + deepLink);
            // TODO show content for deep link
        }
    }
}

And in the example below the deep link is retrieved from Shortcut.

@Override
protected void onCreate(Bundle savedInstanceState) {
    ...

    Uri deepLink = Shortcut.getInstance().getDeepLink()
    if (deepLink != null) {
        Log.d(TAG, "opened with deep link: " + deepLink);
        // TODO show content for deep link
    }
}

Creating Short Links (short mobile deep links)

Shortcut allows you to generate short links immediately, no (potentially slow) backend roundtrip is required. This works as follows:

  1. The SDK generates a unique short link and returns it to you immediately
  2. The generated short link as well as all its parameters (website URL, title, deep links) are sent to the Shortcut backend in the background

This way you get a link immediately that you can present in a share sheet or send out via email, no need to wait for a backend.

Here is an example how to create a Short Link.


SCShortLinkBuilder builder = new SCShortLinkBuilder(getActivity())
      .addWebLink("https://www.pinterest.com/meissnerceramic/allein-alone")
      .addDeepLink("pinterest://board/meissnerceramic/allein-alone");

// Returns null if network unavailble or if for some reason link could not have been generated
String shortLink = builder.createShortLink();

Alternative: Asynchronous creation

There is also an asynchronous way to create a new short link. It works as follows:

  1. The SDK sends the parameters for the short link to the backend
  2. The backend generates a new short link and returns it to the SDK
  3. The SDK notifies you of the new short link via a callback listener

This way you have to wait for the backend to generate the short link, but if there are any errors (e.g. no network connection) then you can react to them.

The implementation of the example above would look like this with the asynchronous call:


SCShortLinkBuilder builder = new SCShortLinkBuilder(getActivity())
      .addWebLink("https://www.pinterest.com/meissnerceramic/allein-alone")
      .addDeepLink("pinterest://board/meissnerceramic/allein-alone");

builder.createShortLink(new SCShortLinkCreateListener() {
    @Override
    public void onLinkCreated(Uri shortLink) {
        Log.i("Shortcut", "Got a short link " + shortLink);
    }
});
Different deep links per platform

If your deep links are not identical for the different platforms your app supports (iOS, Android, Windows Phone) then you can specify them on a per-platform basis:

SCShortLinkBuilder builder = new SCShortLinkBuilder(getActivity())
      .addWebLink("https://www.pinterest.com/meissnerceramic/allein-alone")
      .addAndroidDeepLink("pinterest+something://item/allein-alone")
      .addIosDeepLink("https://www.pinterest.com/meissnerceramic/allein-alone")
      .addWindowsPhoneDeepLink("pinterest://board/meissnerceramic/allein-alone");
Custom domain for short links

If you set up a custon domain for your short links in the Shortcut Manager and want to use it for short links created from the SDK as well, then you need to tell the SDK about it.

This is done either by declaring it in the Manifest.xml file,

  <application>
    <meta-data android:name="sc.shortcut.sdk.shortLinkUrlBase" android:value="http://short.com" />
    ...

or by setting the config programmatically

SCConfig config = Shortcut.getInstance().getConfig();
config.setBaseUrl("http://short.com");

What's next?

Use the Shortcut Manager to create a short-url and set up a deep link to your app specified.

Add deep linking support to your app

Android already has support for deep links baked in. The Shortcut Deep Linking SDK extends the basic built-in functionality with deferred deep links, statistics of app interactions through deep links and short-url generation (suited for sharing).

In order to support deep links in your app add an intent filter to the Activity which you want to get opened when a short link is clicked. This is the entry point of your app. For details check out the Android documentation. The example below demonstrates how you would configure deep link support for the launcher activity in your app's Manifest.xml:

 <activity
      android:name=".MainActivity"
      android:label="@string/app_name" >
      <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>

      <!-- Add this intent filter below, and change the 'scheme' attribute to a unique -->
      <!-- custom scheme that identifies your app. The host and path attribute are     -->
      <!-- optional.                                                                   -->
      <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data
              android:host="shortcut.sc"
              android:scheme="scdemo"
              android:path="/demo"/>
      </intent-filter>
  </activity>

In order to test the deep link support the following command should launch your app:

adb shell am start -a android.intent.action.VIEW -d "scdemo://shortcut.sc/demo"

Alternative installation methods

Add .AAR file as a module

  1. Download the latest .AAR file from the releases page.
  2. In Android Studio import the .AAR file (File -> New Module -> Import .JAR/.AAR).
  3. Then in your app module build.gradle add the following dependency: Gradle dependencies { compile project(':DeepLinkingSDK') }

Use jcenter or mavenCentral

Support for jcenter and mavenCenteral is coming soon.

License

This project is released under the MIT license. See included LICENSE.txt file for details.