Layar Developer Documentation

◀ Back to layar.com

Tutorial - Integrate iPhone SDK

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

Hardware and software Requirements

The Layar SDK requires:

For this tutorial we used:

Create a simple iOS application

1.Launch Xcode , Apple’s latest Integrated Development Environment. Select File->New-> New Project. Select Single View Application and make sure that you are creating an iOS application.

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. Please make sure that the bundle identifier is the same as the one you set when you requested the SDK Key and Secret. We will call our demo project "SDKDemo".

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

4. Add a button "Launch Layar" to the main view in Main.storyboard, which will later launch the campaigns/layer that you created. If you are not familiar with concepts of actions and outlets in iPhone development, please check  iOS Developer Library.

 

In our tutorial, the button is connected to an action named "LaunchLayar". The event type is "Touch Up Inside". Now the ViewController.h file looks like this:

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 SDK. At this moment, we have created an iPhone app with a button called launch layer which is not doing anything yet. You can run it on an iPhone 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 v8.0). 

Firstly, please check the readme.txt file to make sure that you have all the files needed. Unzip the file and place the extracted LayarSDK.framework and Libraries folders in the project folder. 

 2. Project configuration

a. The Layar SDK is built for armv7 architecture. The application in which the Layar 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 SDKDemoapp ->Supporting Files -> SDKDemoapp-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. 

Make sure that there are no spaces before or after the added items.

b. [only for Geo SDK, if you support only Vision SDK skip this step] Add a new key value in the applications info.plist. To do that select the + button and add a field with key name " NSLocationAlwaysUsageDescription", type String and value any string you would like to use (e.g we need your location). Now it should look like this:

Note that the string you will use will be shown once the user launches the geo layer as shown below. It will also be used in the iOS Settings app, under Privacy, Location Services.

c. Any project using the Layar SDK must have the "Minimum OS Version" set to 6.0

d.  Additionally, it must include the following Frameworks:

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

You will also need to import Layar SDK and two more external libraries. To do so select  "+" sign and then "add other" browse the folder where you have placed Layar SDK(In our example, we added both LayarSDK.framework and Libraries folders to the SDKDemo project). Select LayarSDK.framework to add it in the list with the rest Frameworks.

 Repeat this step for external library:

Once all frameworks are added, you will notice that they all appear right below the project directory in the project navigator.

e. We now need to add LayarSDKResources.bundle file (under LayarSDK.framework/Resources) to the app resources, e.g. in the "Supporting Files" group. You can do this by right click on the "Supporting Files" folder ->Add files to.

f. 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.

When building the application the following steps must be taken to ensure that the project links against the "LayarSDK.framework" framework.

The project settings should have the following changes made:

Implement the code which launches the Augmented Reality Scan mode

In this part we will show what you need to implement in order to launch a Campaign or a Vision layer. Please note that campaigns need to be published as pro in order to test with your app.If your campaign links to a geo layer you need to follow the advanced tutorial available here

 Go to file ViewController.h and make the following modifications:

 Go to file ViewController.m and make the following modifications:

NSString *consumerKey = @"yourkey"; 
NSString *consumerSecret = @"yoursecret";
   if (!self.layarSDK)
    {
       self.layarSDK = [LayarSDK layarSDKWithConsumerKey:consumerKey 
andConsumerSecret:consumerSecret andDelegate:self];
    }
    [self.layarSDK viewControllerForScanningWithCompletion:
      ^(UIViewController *viewController)
    {
          [self.layarSDK viewControllerForScanningWithCompletion:
     ^(UIViewController *viewController)
     {
         UIButton* closeButton = [[UIButton alloc] initWithFrame:CGRectMake(0.0f, 40.0f, 80.0f, 30.0f)];
         [closeButton setTitle:@"Close" forState:UIControlStateNormal];
         
         [closeButton addTarget:self action:@selector(dismissModalViewController) forControlEvents:UIControlEventTouchUpInside];
         [viewController.view addSubview:closeButton];
         
         [self presentViewController:viewController animated:YES completion:
          ^{
          }];
        }];  }];

Please note that this code will add a close button. You can customise and change it as you wish.if you already have a navigation controller you do not need to add one.

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

Implement the code which launches a Geo-location layer

In this part we will show what you need to implement in order to launch a geo location layer. Please note that geo layers need to be published in order to test with your app.

 Go to file ViewController.h and make the following modifications:

Go to file ViewController.m and make the following modifications:

    
NSString *consumerKey = @"yourkey";
NSString *consumerSecret = @"yoursecret";
NSString *layerURL = @"layar://yourlayarname";
    
if (!self.layarSDK)
{
	self.layarSDK = [LayarSDK layarSDKWithConsumerKey:consumerKey andConsumerSecret:consumerSecret andDelegate:self];
}
       
[self.layarSDK viewControllerForURL:[NSURL URLWithString:layerURL] withCompletion:
 ^(UIViewController*viewController)
 
{
	if (viewController)
	{
        
        if (viewController.mapViewAvailable)//this will show the map view
            {
            UIButton* mapButton = [[UIButton alloc] initWithFrame:CGRectMake(0.0f, 80.0f, 80.0f, 40.0f)];
            [mapButton setTitle:@"Map" forState:UIControlStateNormal];
            [mapButton addTarget:viewController action:@selector(showMapView) forControlEvents:UIControlEventTouchUpInside];
            [viewController.view addSubview:mapButton];
            }

		[self presentViewController:augmentedRealityViewController animated:YES];
	}
}];

Test your app 

Connect your iPhone:

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

NOTE that Layar SDK does not run on simulator.

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!

Common issues

While working with the SDK you might come across this common errors messages:

Nothing found (when scanning a Page)

Make sure that your Page is published as a Pro Campaign and not as a free one. Also make sure that the campaign belongs to the user you registered to receive the Key and secret.

An error occurred (we did not receive suitable response..) 

 Make sure that:

Localize the app

Since version 7.2.3 the LayarSDK supports localization. You are provided with localizations for English, Dutch, German, French, Spanish and Japanese. To add support for these languages we need to enable localization on our app.

Enable localization for existing languages

In order to enable localization on the app we need to create a ".strings" file. Go to File->New-> New file  and choose  iOS->Resource->Strings File 

click "Next" and name the new file Localizable.strings, and click Create.

Enable "show utilities" from view tabs and press localize

Next, select the project and under info tab add the desired language.In our case it is dutch.

On the new window that will appear select the file we previously created and uncheck the rest of the files.

Now your app supports dutch as well!To test it you can change your mobile language to Dutch remove the existing app and re-run the project!

Localize the app for non supported languages

 In case you would like to provide a language that we do not currently support you will need to edit the created strings file. 

The available strings can be found in the Resource folder. open LayarSDK.framework folder and got to Resources->LayarSDKResources.bundle, right click on it and select show package contents. In the folder that pops up you will find a folder named en.lproj containing the available string files.

Please note that you should try to keep a similar string length to not have the string cut off.