Layar Developer Documentation

◀ Back to layar.com

Tutorial - Integrate iPhone Player SDK v2.0 (Layar Vision)

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

Create a simple iOS application 

Some background information before we get started. In this tutorial, we used:

NOTE that if you are using different XCode version, the interface might look difference from the screenshots attached to this tutorial. 

1. First, we open up Xcode 4, Apple’s latest Integrated Development Environment. Select File->New-> New Project. Select Single View Application and make sure that you are targeting the iOS.

create xcode4.2 project

2. Click Next and fill in the project name "place your name here" and save the file in a convenient place, preferably one that can be easily remembered and accessed in the future. In our case, the project is called "LPDemo". NOTE that we enabled "Use Automatic Reference Counting" in this project.

add product name XCode 4.2

3. Click on "Next" again to finish up creating the app. Now, you have created a new iPhone app called "LPDemo". The project structure will look like this:

newly created LPDemo XCode 4.2

4. Add a button "launch Player" to the main view in ViewController.xib, which will later launch the layer that you created. If you are not familiar with concepts of actions and outlets in iPhone development, please watch this video tutorial to learn how to create UI in XCode.

add launchPlayer button XCode 4.2

In our tutorial, the button is connected to an action named "launchPlayer". The event type is "Touch Up Inside". Once this is done, you will notice that the following line of code is added to the ViewController.h file.

   -(IBAction)launchPlayer:(id)sender;

The entire ViewController.h now should look like:

ViewController header XCode 4.2

Let's have a look at ViewController.m file, a function which handles the "Touch up inside" event of the button is added to the end of the code right before @end.

- (IBAction)launchPlayer:(id)sender {
}

Currently the function is empty and we will leave the file like it is now. Later we need to add some code to this function to launch the Player SDK. At this moment, we have created an iPhone app with a button called launch Player which is not doing anything yet. You can run it on an iPhone device to check it out.

NOTE that Player SDK 2.0 and lower can not run on simulator.

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

player demo interface

Configure the project according to the Player SDK documentation

1. Download and unzip the Layar Player SDK file (in this tutorial, we used Player SDK v2.0).

Firstly, please check the readme.txt file to make sure that you have all the files needed. Move the "Libraries" folder to the LPDemo project directory on the hard disk, such as "user-home-directory/Document/LPDemo/Libraries". There is a bundle file called "PlayerLocalization.bundle", We need to move it to the "LPDemo" folder. So now the LPDemo project structure will look like this:

2. The LayarPlayer SDK requires a minimum installed iOS version of 4.3, and that the device capabilities include OpenGL ES 2 support, a camera, magnetometer, gps and an accelerometer.

The LayarPlayer SDK is also built for ARM7 architecture. The application in which the LayarPlayer SDK is used should reflect this by specifying the following values in the applications .plist for the key UIRequiredDeviceCapabilities:

In XCode, you can add these under LPDemo ->Supporting Files -> LPDemo-Info.plist. Right-Click on any key and click on the small "+" sign next to it to add a new row. Search for "Required device Capabilities" in the dropdown list and add the items mentioned above to the array.

add required devices xcode 4.2

3. Any project using the LayarPlayer SDK must have the "Minimum iOS Version" set to "4.3". 

Open up the info page for your project. Under the Deployment section you should see "iOS Deployment Target". Change it to iOS 4.3.

iOS development target setting

Additionally, it must include the following Frameworks:

Choose the right application target "LPDemo" and open up "Build Phases". Under "Link Binary With Libraries", click on the "+" sign to search and add the frameworks mentioned above.

added frameworks

Once all frameworks are added, you will notice that they all appear right below the project directory in the project navigator. Select and drag all these added frameworks to the Frameworks folder. Now it should look like:

project_frameworks_list_2.0

4. Add "Localization.bundle" file to the project.

Now the entire bundle file appears right under the entire LPDemo project in the project navigator. We will move it to "Supporting Files" folder.

adding bundle files XCode 4.2

5. Armv7 Build configuration

This section explains how to set up build configuration for armv7 application. Most of the configuration can be done under the "Build Settings" tab of the project.

NOTE that the build settings changes made to the Project will be copied to the active target. However, please double check these settings for the target just to make sure.

When building a armv7 application the following steps must be taken to ensure that the project links against the "liblayarplayer.a" static library.

The project settings should have the following changes made:

architecture setting

compiler option v2.0

header search paths v2.0

Layar Player SDK libraries

The LayarPlayer SDK uses some external open source libraries that you might want to use in your own project. In order to avoid symbol conflicts, we're distributing the libraries as separate static libraries together with the LayarPlayer SDK. You need to link you project against the binary static libraries (see screenshot below).

If you use the libraries in your application, you'll need to include the path to the header files in the "Header search paths" of your project's build configuration.

NOTE: If your project already includes these external libraries, you can skip this step.

open source libraries v2.0

Just copy and paste the flags mentioned here into the field in XCode: before pasting, select the line with "Other C Flags" to highlight it, then click once on the value field to turn it into an editable text field where you can paste into. Do not paste when the row is selected (no text field to edit) or if the dialog opens where each field is listed individually, that will mess things up. Note: If your project already contains libsbjson-ios or libMPOAuthMobile, you don't need to include them here.

other linker flags v2.0

Just copy and paste the flags mentioned here into the field in XCode: before pasting, select the line with "Other C Flags" to highlight it, then click once on the value field to turn it into an editable text field where you can paste into. Do not paste when the row is selected (no text field to edit) or if the dialog opens where each field is listed individually, that will mess things up.

other C flags v2.0

6. Change any file which imports Layar Player.hpp file into an Objective-C++ file.

In order to use the LayarPlayer SDK in an application, you need to import the LayarPlayer.hpp in the class file that will launch the LayarPlayer (please see No. 7 below). Note that since it's an Objective-C++ header file, you'll need to change any file that imports it into an Objective-C++ file as well (e.g. MyViewController.mm would import LayarPlayer.hpp, so MyViewController.hpp is the corresponding header file). In practice, all view controllers in the hierarchy above MyViewController, the AppDelegate, and main will need to be renamed as (Objective-)C++ files.

In our project setting, we have renamed the following files:

You can simply rename these files in the project directory on the hard disc first. In the XCode project, import these files via "File" -> "Add files to " and remove the old empty files. 

7. Go to file ViewController.mm and make the following modifications:

     -(IBAction)launchPlayer:(id)sender{

      NSString *layerName = @"layername";
      NSString *consumerKey = @"consumerkey";
      NSString *consumerSecret = @"consumersecret";

      NSArray *oauthKeys = [NSArrayarrayWithObjects:LPConsumerKeyParameterKey, LPConsumerSecretParameterKey, nil];
      NSArray *oauthValues = [NSArray arrayWithObjects:consumerKey, consumerSecret, nil];
      NSDictionary *oauthParameters = [NSDictionary dictionaryWithObjects:oauthValues forKeys:oauthKeys];
      NSArray *layerKeys = [NSArray arrayWithObject:@"radius"];
      NSArray *layerValues = [NSArray arrayWithObject:@"1000"];
      NSDictionary *layerFilters = [NSDictionary dictionaryWithObjects:layerValues forKeys:layerKeys];

      LPAugmentedRealityViewController *augmentedRealityViewController = [[LPAugmentedRealityViewController alloc] init];  // NOTE that here we do not use "autorelease" because we enabled " Use Automatic Reference Counting" when the project      was created. If this option is disabled, you need to manage resource yourself in the code.

      augmentedRealityViewController.delegate = self;

      [self presentModalViewController:augmentedRealityViewController animated:YES];

      [augmentedRealityViewController loadLayerWithName:layerName oauthParameters:oauthParameters parameters:layerFilters options:LPMapViewDisabled | LPListViewDisabled]; 

   }

Please replace "layername", "consumerkey" and "consumersecret" with the right settings in your layer. Please check out here to see how to set and get these parameters from the publishing site. 

8. Connect your iPhone

Choose it from the drop list on the top left corner of Xcode window (near "Run"&"Stop" buttons).

9. Build and run

Choose Product->Build, after you see message "Build successful",choose Product->Run. (or you can just press "cmd+b" to build and then "cmd+r" to run).

That's it! You can find the attached LPDemo app project to play with. Do not forget to replace the layername, consumerkey and consumersecret with your own settings.

Attachments