Tutorial - Integrate Android SDK

In this step by step tutorial, we demonstrate how to integrate the Android Layar SDK into an Android app. The scope of the tutorial is summarized below:

• Create a very simple Android application with one button called "Launch Layar"
• Configure the project according to the SDK documentation (included in the SDK package).
• Implement the code which launches the Augmented Reality View
• Localize the app

Hardware and software Requirements

The Layar SDK requires:

• a minimum installed Android version 2.2
• Android development environment set-up (such as Eclipse)
• Android device that has a back-facing camera (android version 2.2.x and above)

For this tutorial we used:

• Android Developer Tools (ADT) v21.1 (Get the Android SDK )
• Mac OS X version 10.8.2 
• A test device, Samsung Galaxy SII with Android v4.1.2

Create a simple Android application

1.Launch ADT and select File->New-> New Android Application Project and click "Next".

2.In the new window, fill in the information regarding your app. 

Please make sure that the package name is the same as the one you set when you requested the SDK Key and Secret. 

We will call our demo project "SDKDemo". Minimum Required SDK should be set to API 8 and Target SDK should be API 17.

3.Configure project as shown below and click on "Next"

4. Configure the attributes of the icon set. We chose to leave default option as is. Once you finish with configuration click on "Next".

 5. in the new window check the box Create Activity and select New Blank activity. Click on "Next"

6. Fill in the activity name. We will name our activity LaunchLayar. When done click "Finish"

7. Now, you have created a new Android app called "SDKDemo". The project structure will look like this:

8. Browse through the folder navigation SDKDemo->res->layout and open file activity_layar.xml. Once the file opens, select tab Graphical Layout.

9. Delete the Hello world reference. Drag and drop a button to the Graphical Layout from Form Widgets tab.

10.  Browse through the folder navigation SDKDemo->res->values and open strings.xml and add the following line:

   <string name="Launch_Layar">Launch Layar</string>

The file should now look like this:

11. Now go back to file activity_layar.xml and replace the references to button to Launch_Layar. We will also add onClick="launch". We will later create a launch method that to launch Layar AR. The file should now look like this:

 At this moment, we have created an Android app with a button called Launch Layar which is not doing anything yet. You can run it on an Android device to check it out.

Next, we will configure the project to include the Layar SDK.

Configure the project according to the Layar SDK documentation

1. Download and unzip the Layar SDK file (in this tutorial, we used SDK v7.2.2). 

Firstly, please check the readme.txt file to make sure that you have all the files needed. Unzip the file and place the extracted folder in a place where you can easily track it.

 2. Import the Layar Vision SDK library project into Eclipse

As the eclipse project files are included in the SDK, you just need to import the project to your workspace. This can be achieved using File > Import->Existing Projects into Workspace

Click "Next" and select the Layar Vision SDK project directory and select project "layar_vision_sdk", click "Finish" 

3.Add the Layar Vision SDK library project to your own application

After importing the library project, you can reference the library in your project. To do so, right click your applications project, select "Properties", and go to the "Android" tab. In the "Libraries" section, click "Add..." to add the "layar_vision_sdk" library project.

 NOTE: The Layar Vision SDK comes with some library .jar files in its libs folder. This may cause conflicts if your application is using other versions of the same libraries (e.g. android-support-v4.jar). If that occurs, you should remove the conflicting .jar file from your project, and (if needed) replace the .jar file in the Layar Vision SDK with the newer version. 

4.Enabled manifest merging

The Layar Vision SDK declares a couple of Activities and permissions in its own AndroidManifest.xml. These declarations must be merged into your applications AndroidManifest.xml. While it is possible to manually copy the contents into your AndroidManifest.xml, but it is easier to enable manifest merging in your project by adding the following to your applications's project.properties file:

 manifestmerger.enabled=true

NOTE: In order for manifest merging to be possible, the targetSdkVersion and minSdkVersion of your application and the Layar Vision SDK should be the same.

NOTE2: Eclipse will not pick up the changes in the project.properties automatically. If you see errors in the logs about missing Activities, please try to restart Eclipse. This should resolve the issue.

Implement the code which launches the Augmented Reality View

In order to use the Layar SDK in an application, all you need to do is interact with the LayarVisionSDK class. This contains two simple static methods for initialization and starting the Activity.

•  Initialization

 LayarVisionSDK.initialize(Context context, String oauthKey, String oauthSecret);    

  Before using the Layar Vision SDK, you need to initialize it by providing your application Context and your OAuth credentials. These credentials are used to authenticate your application and to filter the visual search results to include only campaigns from your layar account. This method only needs to be called once in your applications lifetime.  

•   Starting Activity   

   LayarVisionSDK.startLayarVisionActivity(Context context);     

 After initialization, you can simply start the LayarVisionActivity. This will launch the Layar Camera view in scan mode, which allows your user to scan and interact with your campaigns.
In LaunchLayar.java file, we will create a function named "launch" :

public void launch(View view) {String oauthKey = "your oauthKey"; 

String oauthSecret = "your oauthSecret"; 

LayarVisionSDK.initialize(this, oauthKey, oauthSecret);

LayarVisionSDK.startLayarVisionActivity(this, menuHolder); } 

Please use the correct "key" and "secret" that you have obtained from Layar when you requested the SDK.

Our LaunchLayar.java file now looks like this:

Build and run

Before you can run your application on a device, you must enable USB debugging on your device.
 - On most devices running Android 3.2 or older, you can find the option under Settings > Applications > Development.
- On Android 4.0 and newer, it's in Settings > Developer options.
Once set up and your device is connected via USB, install your application on the device by selecting Run > Run  from the Eclipse menu bar.

Select the device you want to use and press "Ok". That's it!

Localize the app

Since version 7.2.2 the LayarSDK supports localization. You are provided with localizations for English, Dutch, German, French, Spanish and Japanese.
If you are interested in adding another language currently not supported you need to follow these steps:
1.On your project right click on folder res and add a new folder

2. Name the folder values- the initials of the language you would like to add in our case the name is values-it (for italian)

3. Copy on this folder the strings-player.xml file that you can find on Layar SDK file under res->values folder. Open this file and translate the Strings. For your SDK app you can limit translation to Vision AR View strings.