android-quick-start.md

Android Quick-Start Guide

This quick start guide shows you how to get up and running fast with the Branch SDK for Android.

Step 0 - Sign Up & Setup

If you don't already have a Branch account, head here and sign up for one. It's free!

The Dashboard

Our dashboard is the starting point for adding apps as well as tracking users of your app.

To get started, point your browser to https://dashboard.branch.io/. If you haven't created an account before, you can signup and get taken through the basic setup right away. If you've signed up already, simply navigate to the Summary page and click the dropdown button in the top right. Choose "Create new app."

You will be prompted to enter a name for your new app. Do so and press "Create."

Step 1 - Register Your App

Getting a Branch Key

Branch Keys are unique per-app and required by the SDK to identify your app. If you've signed up, you can find your Branch key at the top of the Settings page in your dashboard.

Scroll down to the App store information section and select your app by searching for it within the Google Play Search box provided. If youre app is published outside of the Play Store, you can alternatively provide a Custom URL to APK that points to a publically accessible location where users can download your app - this comes in handy if you haven't yet published your app and want to try out the features of Branch before you do.

Step 2 - Set Up Your IDE

This part depends on your personal preference:

• if you prefer Android Studio jump straight to Step 3a.
• if you are an Eclipse user, jump straight to Step 3b.

If you are new to Android development and are not familiar with either of the above, we recommend installing Android Studio to get started.

Step 3a - Android Studio

As Android Studio makes use of Gradle dependencies and the Branch SDK is hosted in Maven Central, the set up process is straightforward.

• Right click on the main module within your project (this is called 'app' by default).
• Select Open Module Settings.
• Within the Dependencies tab, click the + button at the bottom of the window and select Library Dependency.
• Type branch, and hit the enter key to search Maven Central for the Branch SDK Library.
• Select the latest io.branch.sdk.android:library item listed and accept the changes.

Android Studio will then run a Gradle Sync automatically and will import the library files that are required for you.

To test that you've imported the dependencies successfully, declare a Branch object as follows.

Branch branch;

If there's no error highlighted in red, you're ready to go to Step 4.

Step 3b - Eclipse

Download or clone the Branch SDK to your machine, and import it into your Eclipse workspace alongside the project that you want to integrate with Branch.

• Go to File > Import
• Browse to the directory that you unzipped the project to and select it in the dialog.
• Check Copy projects into workspace, and hit finish to complete the import.

At this point the project will not build, and you'll see some problems relating to a missing library. To correct that:

• Right click on your project in the left hand pane and select Properties.
• Select Android from the left hand pane, and in the Libraries section on the right, click Add.
• Select Branch-SDK from the list of available library projects, and hit ok.

Select "Android" on the left, then click the "Add" button, then select Branch-SDK to add the project to your app as as a dependency.

Once that's done, you'll see a green tick next to the "Library" list, confirming that it's been added correctly. Click "OK" to confirm.

To test that you've imported the dependencies successfully, declare a Branch object as follows.

Branch branch;

If there's an error highlighted in red, hover over it and select Import 'Branch' (io.branch.referral). You're now ready to go to Step 4.

Step 4 - Create a Branch Session

Configuring your Branch key

Now you'll need the Branch key that you created in the Branch Dashboard.

Open up strings.xml and add your key as a String value.

<string name="branch_key">your Branch Key</string>

Now add a reference to the value that your just created in your AndroidManifest.xml file, within the Application element.

<application .. >
	
	<!-- Your existing activities, intent filters and associated attributes. -->
	<activity .. >
		..
	</activity>

	<!-- The reference to the string value that you created in strings.xml, with name as shown. -->
	<meta-data android:name="io.branch.sdk.BranchKey" android:value="@string/branch_key" />
	
</application>

The Branch SDK looks for the io.branch.sdk.BranchKey meta-data value when it is initialised. If you want to base other projects on this one and would like to track link analytics separately in the dashboard, you need only to create a new app in the Branch dashboard and update the value in strings.xml with the new key in order to associate the project with the new project.

This guide assumes that you're familiar with the Android UI lifecycle. A single Branch object instance is used per Activity or Fragment, so declare an object at the class-level, and you can call this in every Activity or Fragment where you need to interact with Branch; if it has already be initialised elsewhere in your app, the same instance will be returned.

public YourClass extends Activity {
	Branch branch;
	...
}

In the overridden onStart method in your Activity or Fragment, get an instance of the singleton Branch object and assign it to the class-level handle that you just declared.

@Override
protected void onStart() {
	super.onStart();

	branch = Branch.getInstance(this.getApplicationContext());
	...
}

Note: If you have already integrated the SDK via the two-parameter getInstance(context, "app key") method, it has been deprecated. You should update your project to store your branch key as meta data in your AndroidManifest file.

Getting a session

The next step is to call initSession(...). This connects to the Branch servers in preparation for receiving the links that you're to configure, or to look up the link that your app has just received.

As this action is Asynchronous, the response is taken care of by a BranchReferralListener() which we need to configure first.

Branch branchReferralInitListener = new BranchReferralInitListener() {
	@Override
	public void onInitFinished(JSONObject referringParams, BranchError error) {
		
		// Do this when a response is returned.
		...
				
	}
}

Next, call initSession() as shown here to initialise the Branch session; the last two parameters pass the data associated with an incoming intent, and this refers to the activity context.

Note: If you're running this in a Fragment, use getActivity() instead of this.

branch.initSession(branchReferralInitListener, this.getIntent().getData(), this);

Important: Closing the session

In order for the SDK to know that you're finished with the Branch object, it's important to close the session when you're done, so add the closeSession() call to your onStop method.

@Override
protected void onStop() {
	super.onStop();
	
	branch.closeSession();
}

That's all there is to it. The next step is to create some deep links for your users to share.

Creating deep links from within your app

branch.getShortUrl(tags, "channel1", "feature1", "1", obj, new BranchLinkCreateListener() {

	@Override
        public void onLinkCreate(String url, BranchError error) {

    		// Backwards try-catch to see if error is null...does the job, not elegant though.
		try {
			Log.w(TAG, "onLinkCreate() ERROR: " + error.getMessage());
			
		} catch (Exception e){
			Log.v(TAG, "onLinkCreate() URL: " + url);
			tvShortUrl.setText(url);
			tvShortUrl.setOnClickListener(new View.OnClickListener() {

				@Override
				public void onClick(View v) {
					Intent browserIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(((TextView)v).getText().toString()));
                                        startActivity(browserIntent);
				}
			});
		}
        }
});