The new empty app includes a handful of default files, including the manifests/AndroidManifest.xml file (this is if you have the Android view activated. In the Project view, it is in app/src/main). Every application must have an AndroidManifest.xml file in its manifest directory that tells the Android system what it needs in order to run the app's code, along with other metadata.

Let's set this up first. Open your AndroidManifest.xml file in the editor. Modify it to read it as follows:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.cardbookvr.skeleton" >

   <uses-permission android:name="android.permission.NFC" />
   <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.VIBRATE" />

    <uses-sdk android:minSdkVersion="16" 
    android:targetSdkVersion="19"/>
    <uses-feature android:glEsVersion="0x00020000" android:required="true" />
    <uses-feature android:name="android.hardware.sensor.accelerometer" android:required="true"/>
    <uses-feature android:name="android.hardware.sensor.gyroscope" android:required="true"/>

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <activity
            android:name=".MainActivity"

            android:screenOrientation="landscape"
            android:configChanges="orientation|keyboardHidden|screenSize" >

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
                <category android:name="com.google.intent.category.CARDBOARD" />
            </intent-filter>
        </activity>
    </application>

</manifest>

The package name show in the preceding listing, package="com.cardbookvr.skeleton", may be different for your project. The <uses-permission> tag indicates that the project may be using the NFC sensor, which the Cardboard SDK can use to detect the smartphone that has been inserted into a Cardboard viewer device. The Internet and read/write storage permissions are needed for the SDK to download, read, and write the configure setup options. We will need to do a little more work in order to handle permissions properly, but that happens in another file, which we will discuss later.

The <uses-feature> tag specifies that we'll be using the OpenGL ES 2.0 graphics processing library (http://developer.android.com/guide/topics/graphics/opengl.html).

It's also strongly recommended that you include the accelerometer and gyroscope sensor uses-feature tags. Too many users have phones lacking one or both of these sensors. When the app fails to track their head motions correctly, they may think that the app is to blame rather than their phone. Within the <application> tag (the default attributes of which were generated when we created the file), there's an <activity> definition named .MainActivity and screen settings. Here, we specify the android:screenOrientation attribute as our Cardboard app uses the normal (left) landscape orientation. We also specify android:configChanges that the activity will handle itself.

These and other attribute settings may vary based on your application's requirements. For example, using android:screenOrientation="sensorLandscape" instead will allow either normal or reverse landscape orientations based on the phone's sensor (and trigger the onSurfaceChanged callback when the screen flips).

We specify our intent metadata in the <intent-filter> tag. In Android, an intent is a messaging object used to facilitate communication between applications' components. It can also be used to query the apps that are installed and match certain intent filters, as defined in the app's manifest file. For example, an app that wants to take a picture will broadcast an intent with the ACTION_IMAGE_CAPTURE action filter. The OS will respond with a list of apps installed which contain activities that can respond to such an action.

Having defined the MainActivity class, we'll specify that it can respond to the standard MAIN action and match the LAUNCHER category. MAIN means that this activity is the entry point of the application; that is, when you launch the app, this activity is created. LAUNCHER means that the app should appear in the home screen's launcher as a top-level application.

We've added an intent so that this activity will also match the CARDBOARD category because we want the other apps to see this as a Cardboard app!

Google made major changes to the permissions system in Android 6.0 Marshmallow (API 23). While you still must include the permissions you want within the AndroidManifest.xml file, you must now also call a special API function to request permissions at runtime. There are a variety of reasons for this, but the idea is to give the user finer control of app permissions, and avoid having to ask for a long list of permissions during install and at runtime. This new feature also allows users to selectively revoke permissions after they have been granted. This is great for the user, but unfortunate for us app developers, as it means that we need to do significantly more work when we need access to these protected features. Essentially, you need to introduce a step which checks if a particular permission is granted, and prompts the user if it is not. Once the user grants permission, a callback method is called, and you are free to do whatever it was that needed permission. Alternatively, if the permission was granted the whole time, you can proceed to use the restricted feature.

At the time of writing, our project code and the current version of the Cardboard SDK do not implement this new permission system. Instead, we will force Android Studio to build our projects against an older version of the SDK (API 22) so that we side-step the new features. It is possible that, in the future, Android might break backwards compatibility with the old permissions system. However, you can read a very clear guide on how to use the new permissions system in the Android documentation (refer to http://developer.android.com/training/permissions/requesting.html). We hope to address this, and any future issues in the online GitHub repositories, but bear in mind that the code in the text, and the provided zip files, may not work on the newest version of Android. Such is the nature of software maintenance.

Let's apply that workaround to build against version 22 of the SDK. Odds are that you just installed Android Studio 2.1 or above, which comes with SDK 23 or above. Whenever you create a new project, Android Studio does ask what minimum SDK you would like to target, but does not let you choose the SDK used for compilation. That's OK, because we can manually set this in the build.gradle file. Don't be afraid; the build toolset is big and scary, but we're only tweaking the project settings a little bit. Bear in mind that there are a couple of build.gradle files in your project. Each one will be within its corresponding module folder on the filesystem, and will be labeled accordingly within the Gradle scripts section of the Android flavor of the project view. Were looking to change build.gradle for the app module. Modify it to look like this:

apply plugin: 'com.android.application'

android {
    compileSdkVersion 22
    ...

    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 22
        ...
    }
    ...
}

dependencies {
    compile 'com.android.support:appcompat-v7:22.1.0'
    ...
}

The important changes are to compileSdkVersion, minSdkVersion, targetSdkVersion, and that last one in dependencies, where we changed the version of the support repository we are linking to. Technically, we could eliminate this dependency entirely, but the project template includes a bunch of references to it, which are a pain to remove. However, if we leave the default setting, Gradle will most likely yell at us about mismatching versions. Once you've made these changes, there should be a yellow bar at the top of the editor with a link that says Sync now. Sync now. If you're lucky, the Gradle sync will finish successfully, and you can go on your merry way. If not, you might be missing the SDK platform or other dependencies. The Messages window should have clickable links to install and update the Android system appropriately. If you hit an error, try restarting Android Studio.

From this point on, you might want to avoid updating Android Studio or your SDK platform versions. Pay special attention to what happens when you import your project on another computer or after updates to Android Studio. You will likely need to let the IDE manipulate your Gradle files, and it may modify your compile version. This permissions issue is sneaky, in that it will only reveal itself at runtime on phones running 6.0 and above. Your app may appear to work just fine on a device running an older version of Android, but actually run into trouble on newer devices.