Deeplinking Guide

Introduction

Firstly thanks for your interest in the Vodafone developer offering. In particular it is great to see that you are engaging with Vodafone to publish your Android apps via Vodafone AppSelect.

We are continually striving to give you as developers the best support that we can. We have introduced two new concepts - Deep links and Universal IDs (also known as UNIVIDS) that will help you as a developer to better promote your apps.

These concepts will allow you to link directly to your apps that you have uploaded to Vodafone AppSelect from a web page, a banner or even directly from an Android app. That gives you the flexibility to create campaigns that not only generate interest for the consumer, but will take them directly to your app. When we talk about apps we are generically referring to either applications or games.

In the next few pages we´ll dive into more detail about what Deep links and Universal IDs are and how you can create, configure, manage and use them.

Deep links and UNIVIDS

What is a deep link and how do you use it?

Essentially a deep link is a reference that allows you to give direct access to your apps in Vodafone AppSelect.

It allows you to give this direct access either from

a mobile browser or
from an Android application

We provide the tools you need to manage your deep links within the Vodafone Upload Platform (http://developer.vodafone.com/upload).

So imagine you have uploaded your "football" app via the Vodafone Upload Platform. Using an http link that you can create via the tools we provide, you can link from a mobile web page directly to your football app, or, you can use a link in your Android app that takes the user directly to your football app.

One thing is important here, if you are using the link from an Android app, that will only work on the target device when the Vodafone AppSelect client is on that device - that's the client that is used to access, browse and purchase from Vodafone AppSelect.

A deep link that can be used to access your app directly from a mobile browser has the format:

http://<Vodafone Appselect Address>/<pointer to your article>

A deep link that is used directly from an Android app has the format:

vfstore://<pointer to your article>

You´ll see this in more detail when we look at the tools that you can use to create and manage your deep links - you will also see how you can use these deep links in more detail in the section "Code Examples".

Before moving onto that let´s take a look at the second concept we mentioned Universal IDs or UNIVIDs.

What is a UNIVID and how do you use it?

When you have been using Vodafone AppSelect you will have seen that you can publish to apps to various different countries. As you can imagine, internally Vodafone AppSelect has to be able to manage these articles on a per country base. We want to make that transparent and easier for you to handle, that´s where UNIVIDs come into play.

A UNIVID is a mechanism that provides you a constant static deep link that is mapped to content that has been published in different countries. Or to rephrase that, with a UNIVID you have a simple mechanism to specify which content can be reached per country.

You can embed UNIVIDs into mobile web pages or Android apps in the same way that you can embed a deep link.

In the following example you´ll see why the UNIVID concept is so powerful. You embed the UNIVID once and then you have the possibility to change the actual apps that that UNIVID refers to - and you don´t have to change code that you have embedded in your app or on your mobile browser site - the UNIVID stays constant.

Let´s look at an example. Let´s say that you have uploaded and published your first app "Premier" - which is an app that gives details about the Premier Football League in the UK.

As a first simple example you could go to your app "Premier" (we´ll explain how the user interface works later) and configure a UNIVID - let´s call it "SOCCER" - that links to your "Premier" app in the UK.

In the same way you were able to embed deep links into a mobile web page or an Android app, you can now embed your UNIVID called "SOCCER". A user in the UK clicking on the link to the UNIVID "SOCCER" would directly access the app "Premier" in the UK.

Since this UNIVID currently only links to "Premier" you´re probably wondering what the power of UNIVIDs is. Imagine, you now write a version of your app that covers the Bundesliga in Germany - you configure your UNIVID "SOCCER" to additionally link to this "Bundesliga" app in Germany.

You can now embed one constant UNIVID "SOCCER" but - and this is the power of UNIVIDs - a German customer will automatically reach the "Bundesliga" app and the UK customer the "Premier" app.

As you build out your apps to support say "Eredivisie" (the Dutch football league) you can configure the "SOCCER" UNIVID to point to this app in Holland. A Dutch user will automatically see that app.

Since the UNIVID "SOCCER" is constant you can configure this to link to more apps as you make them available.

You can see that UNIVID are an incredibly powerful mechanism that you can use to offer - and manage - content. You could configure a "Top Apps of the month" UNIVID and allocate a different app each month per country.

The beauty is that the link you use on your mobile web site or in your Android app always remains the same.

In the same way that you can embed a deep link into your mobile web site or Android app you can do the same with UNIVIDs.

The format of a UNIVID is similar to that of a deep link

A UNIVID that can be used to access your app directly from a mobile browser has the format:

http://<Vodafone Appselect Address>/<Your UNIVID>

A deep link that is used directly from an Android app has the format:

vfstore://<Your UNIVID>

In the section "Code examples" you will see how you can use these links.

Code examples

Before we start to describe how to create, configure and manage your deep links and UNIVIDS let´s take a quick look at how you would use them in your code.

In a (mobile) web page you would add a hyperlink with the target of the deep link or UNIVID that you want to address.

<a href=" http://<Vodafone Appselect Address>/<pointer to your article>.">Click here to get my great app.</a>

<a href=" http://<Vodafone Appselect Address>/<Your UNIVID>.">Click here to get my great app.</a>

If Vodafone AppSelect is installed on the device, it will be launched and will show the article page.
If Vodafone AppSelect is not installed, the browser will show the article page in the Mobile Browser Shop.

To deep link into the Vodafone AppSelect client from your Android app you would use the following code

Intent intentStart = new Intent();
intentStart.setData(Uri.parse("vfstore://"));
intentStart.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK
| Intent.FLAG_ACTIVITY_CLEAR_TOP
| Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED);
context.startActivity(intentStart);

Further down this document we describe the tools that you can use to create, configure and manage deep links and UNIVIDS. You will see actual examples of the deep link and UNIVID links there.

Format of a UNIVID

Although you need only copy and paste your UNIVID to use it, it´s probably interesting for you to understand what the format of a UNIVID is.

The format of the UNIVID is:

!<hash of user name><UNIVID name>

The addition of the ! is added to the actual UNIVID name to ensure that UNIVIDS are unique within the overall Vodafone AppSelect proposition.

The UNIVID used in this example it is "!RVVSLTAxLUJvdXRpcXVlSOCCER" where

RVVSLTAxLUJvdXRpcXVl is the hash of the user name and
SOCCER is UNIVID name that was entered in the system

Managing your deep links and UNIVIDs

We´ve talked about what deep links and UNIVIDs are and how they can be used so let´s now look at the tools that we have in order to create, configure and manage them.

These tools are available in the Vodafone Upload Platform (http://www.developer.com/upload) and you will have to login to your publisher account.

You will then be able to access your deep links and UNIVIDs via the top menu bar.

After clicking on "My Deep links", you will see the sub-menus "My Deep links" and "My Univids". The links provide access the developer's deep links and UNIVIDs respectively.

MyDeeplinks

Let´s take a look at what "MyDeep links" allows you to do.

You will see information for each app that has been published per country. You can select the country in which your apps have been published.

It is important to understand that the app has to be in Vodafone AppSelect to be able to have a deep link. What that means is that you will only see deep links for apps that have passed the internal Vodafone QA process - so it may take some time before you see your apps in your deep link list.

Let´s take a look at what information you see when you select the "MyDeeplinks" view.

The information you see is:

Id - this is the Vodafone internal Id number that is used to identify your app in Vodafone AppSelect. You´ll see this appearing in the deep link URL
Name - this is the name of the application
Description - this is the short description of the app. It is taken directly from the short description you entered when uploading the app
Links - these are the deep links that you can copy and paste into either your mobile web site or your Android app. These links would replace the sample entries that were described in the section "Code Examples"

Now - remember we said that we could create and configure UNIVIDs.

Let´s assume that we have not set up any UNIVIDs. You can initially create a UNIVID for an app and a specific country.

So going back to our example of the UNIVID "SOCCER" - within the list of Article Deep Links you can create the UNIVID initially for the UK by clicking on the "New UNIVID" button.

This then opens the dialogue "Create UNIVID" and I can enter "SOCCER" as the name:

Now the UNIVID "SOCCER" has been created and it is configured with the "Premier" app published in the UK.

What you now see is

Name - this is the actual UNIVID - (we´ll come back to the format of that in the next section)
the links that you can in embed in your mobile web site or Android application (this is analogue to the deep link)
and a list of the apps that are linked to the UNIVID - in this case we see that the app "Premier" is associated to the UNIVID "Soccer" for the UK.

You also have the ability to delete individual apps from a UNIVID or all apps associated with a UNIVID.

By returning to "MyDeep links " you can add an additional app to an existing UNIVID.

Following the example above - by selecting the app "Bundesliga" and "link to existing UNIVID" ..

.. you receive the list of your UNIVIDs and, in this case, by selecting "set for" Germany (clicking on the German flag) the app "Bundesliga" has been added to the UNIVID "Soccer".

You now see that the UNIVID "Soccer" is associated with the app "Premier" for the UK and "Bundesliga" for Germany.

Going back to the example above, then next step would be to select "Eredivisie" and add that for Holland.

MyUNIVIDs

You can view the UNIVIDS that you have created via the "MYUNIVIDs" menu.

The list returned contains the UNIVIDs that you have created, and also an overview of the apps that you have associated with that UNIVID.

What you now see is

the actual UNIVID - (we´ll come back to the format of that in the next section)
the links that you can in embed in your mobile web site or Android application (this is analogue to the deep link)
and a list of the apps that are linked to the UNIVID

You also have the ability to delete individual apps from a UNIVID or all apps associated with a UNIVID.

If you delete all apps associated with a UNIVID the UNIVID is also deleted.

The user experience

Let´s take a look at what a user will see when the deep links or UNIVIDs are selected on the client.

It´s important to note that currently all Vodafone Android devices support the Vodafone AppSelect proposition. Vodafone plan to provide support for "vanilla" (i.e. non Vodafone branded devices) in early 2012.

When a deep link or a UNIVID is selected on an device that has the Vodafone AppSelect client installed, firstly the Vodafone AppSelect client is activated, then the detail page of the associated application is shown.

From a mobile browser, the user will be presented with a browser view of the application detail page which you can see below.

If an error occurs when a deep link or UNIVID is selected the end user is presented with an appropriate error message.

Let´s firstly take a look at some of the errors that can occur, what their causes are and what the user would see. Following that, in the section "Golden Rules" we´ll talk about some of the things that you can do as a developer to avoid these error situations.

As you know, when you upload an app through the Vodafone Upload Platform you can select the target devices for your app. Let´s assume that you have created an app and this app deep links to another specific app. The user clicks on the deep link - now, if the device that the user is using was not one of the devices associated with the app behind the deep link the user will see the error message below:

A user would also get that error message if the app that the deep link links to is no longer available in the Vodafone AppSelect store. Again - we´ll look at the reasons for that in the next section.

A similar error message is displayed if a user clicks on a UNIVID that links to an app that is not associated with the device:

In the example above, the UNIVID "SOCCER" has an app associated with it that cannot be displayed on the device used.

Remember when we were talking about UNIVIDs - you can associate an app per country in the UNIVID. In the example we used, we associated the three apps "Premier", "Bundesliga" and "Eredivisie" to the countries UK, Germany and Holland in the UNIVID "Soccer". But what happens if a user from say Italy clicks on the link to the UNIVID "Soccer" ? Since there is no app associated with Italy within the UNIVD the user will get the following error message.

Golden Rules

In the section above we showed you the errors that may occur. As a developer there are certain things that you can do to - let´s call them "the Golden Rules" that you need to keep in mind when you are working with deep links and UNIVIDs.

Golden Rule #1:

The first Golden Rule is to think about device reach. What do we mean ? When you upload an app via the Vodafone Upload Platform you are presented with a list of devices that your app supports. This device list is based upon the entries that you made in your Android manifest. During the upload process you have the chance to deselect certain devices if you want - i.e. to remove devices where you feel that your app will not run - or will not run in an optimum fashion.

What you need to remember is - if you are using a deep link to one of your apps that is only available on a limited number of devices, then only a user with one of those devices will have a positive experience when clicking on the deep link - otherwise the user will see the type of error that we talked about above.

Golden Rule #2:

As we said above, if your deep link points to an app that is no longer available in Vodafone AppSelect (or your UNIVID has an app associated it with it that is no longer available) the user will receive an error when trying to access this app.

The cause of this is if the status of you app has changed from the "Published" state - deep links are only available for apps that are published in the Vodafone AppSelect store. As a developer you cannot select "Unpublish my app" but the status of your app may change. As you know, Vodafone has adminstrators who look after the content in the Vodafone AppSelect proposition. If - for some reason - your app is moved to a non-published state you will get a message in your Inbox on the Vodafone Upload Platform. At that point in time, your deep link is no longer valid - it would point to an app that is no longer published and therefore a user trying to access it would receive an error. You would therefore need to remove any deep links that refer to that app. So the Golden Rule here is to make sure you check your Inbox to monitor what is happening with your apps.

A final point

Let´s take another step back - remember you can only deep link to content that has been published in a specific country. The Vodafone tools on the Vodafone Upload Platform only return a list of apps that have been published. You therefore only see valid deep links that you can directly use and valid, published articles that may wish to associate to a UNIVID.

However, you cannot control from which country a user is accessing your deep link or UNIVID. If an Italian user accesses a UNIVID which does not have an app associated for Italy she will get an error message. This can of course be the exact behaviour that you want, if your apps are so country specific that they are not relevant for other countries. However, if one of your country apps could be used as a "default app" for the other countries you could associate this within the UNIVID. That being said, you should make careful use of such associations if the "default app" is not really relevant for all countries.