{"_id":"5cad35180f496b002cbd039a","category":{"_id":"5cad35180f496b002cbd0364","version":"5cad35180f496b002cbd03f0","project":"578c4badbd223d2000cc1441","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-03-17T19:00:39.218Z","from_sync":false,"order":2,"slug":"getting-started-android","title":"Android - Platform Setup"},"project":"578c4badbd223d2000cc1441","user":"576c22a3808cf02b00d37419","parentDoc":null,"version":{"_id":"5cad35180f496b002cbd03f0","project":"578c4badbd223d2000cc1441","__v":0,"forked_from":"5c12c34fccfacf00f9af2195","createdAt":"2018-04-23T20:03:35.726Z","releaseDate":"2018-04-23T20:03:35.726Z","categories":["5cad35180f496b002cbd0362","5cad35180f496b002cbd0363","5cad35180f496b002cbd0364","5cad35180f496b002cbd0365","5cad35180f496b002cbd0366","5cad35180f496b002cbd0367","5cad35180f496b002cbd0368","5cad35180f496b002cbd0369","5cad35180f496b002cbd036a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.14.0","version":"2.14.0"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-17T20:14:44.025Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"To distribute your application follow the instructions for each respective platform. If you are distributing with Viro, please follow our [Attribution](doc:attribution) guidelines. Links provided below. \n\nAndroid Cardboard Distribution:\nhttps://developers.google.com/vr/distribute/cardboard/\n\nGoogle Daydream Distribution:\nhttps://developers.google.com/vr/distribute/daydream/\n\nOculus Gear VR Distribution: \nhttps://developer3.oculus.com/documentation/publish/latest/\n\n[block:api-header]\n{\n  \"title\": \"Building for Production\"\n}\n[/block]\nFirst make sure you prepare your apk to be signed. More information on this can be found from the React native documentation:\nhttps://facebook.github.io/react-native/docs/signed-apk-android\n\nOnce you have prepared your gradle files for a signed apk, you can build a production Android app that bundles your assets and code into an apk. To do this run the following from your project root android directory (ProjName/android) in terminal:\n\nTo build for GVR or ARCore release:\n```./gradlew assembleGvrRelease```\n\nTo build for Oculus Gear VR run:\n\n```./gradlew assembleOvrRelease```\n\n[block:api-header]\n{\n  \"title\": \"Updating Android project to Target API level 28\"\n}\n[/block]\nThe following steps are needed to update your Android project to Target API Level 28. This is required as of November 2018: Google Play Store no longer accepts APKs built using any Target older than 26.\n\nThe instructions below are for Target 28. If due to other dependency issues you prefer Target 26 or 27 to Target 28, simply replace the Gradle version numbers below to what works best for your project setup.\n\n1. Now open `android/build.gradle` file.\n  * If not already present, add `google()` under `buildscript -> repositories` and `allprojects -> repositories` sections.\n  * Under `buildscript -> dependencies`, change gradle classpath to `classpath 'com.android.tools.build:gradle:3.2.1'`\n2. Open `android/gradle/wrapper/gradle-wrapper.properties` and update `distributionUrl` to `distributionUrl=https\\://services.gradle.org/distributions/gradle-4.6-all.zip`\n3. Open `android/app/build.gradle` and make the following changes\n  * Update compileSdkVersion to `compileSdkVersion 28`\n  * Update buildToolsVersion to `buildToolsVersion '28.0.3'`\n  * Add `flavorDimensions \"platform\"` under `buildToolsVersion`, if not already present.\n  * In the `defaultConfig` section, update targetSdkVersion to `targetSdkVersion 28`.\n  * In the `dependencies` section, update `compile 'com.android.support:appcompat-v7:25.0.0'` to `implementation 'com.android.support:appcompat-v7:28.0.0'`\n  * **(Needed only if you *are* updating to `target 28`. Not needed for targets 26 or 27)** Update our AWS dependencies (needed for key validation) to the following\n   ```\n       implementation 'com.amazonaws:aws-android-sdk-core:2.7.7'\n       implementation 'com.amazonaws:aws-android-sdk-ddb:2.7.7'\n       implementation 'com.amazonaws:aws-android-sdk-ddb-mapper:2.7.7'\n       implementation 'com.amazonaws:aws-android-sdk-cognito:2.7.7'\n       implementation 'com.amazonaws:aws-android-sdk-cognitoidentityprovider:2.7.7'\n   ```\n  * Finally, change all `compile` tags in `dependencies` section to `implementation`.\n\nThat's it! Sync your Android Project once these changes are done and start building.\n[block:api-header]\n{\n  \"title\": \"Targeting Older Android Builds\"\n}\n[/block]\nDepending on you users and application, you might need to target and build with older versions of the Android SDK in Android Studio. To do so, simply lower the **minSdkVersion** version number as specified in the build.gradle file to the desired version. You will also need to inform Android about the version override in your Android manifest file with the **overrideLibrary* tag: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"utf-8\\\"?>\\n<manifest xmlns:android=\\\"http://schemas.android.com/apk/res/android\\\"\\n    package=\\\"com.example.virosample\\\">\\n  \\n  \\t<!-- Required to read the paired viewer's distortion parameters -->\\n    <uses-permission android:name=\\\"android.permission.READ_EXTERNAL_STORAGE\\\"/>\\n    ... other permissions ...\\n   \\n    <!-- Perform our override here -->\\n    <uses-sdk tools:overrideLibrary=\\\"com.viro.renderer\\\"/>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nDepending on the features that you want to use in your application, there is also a minimum sdk version number to which you can lower the minSdkVersion towards for them to function properly. These features and their corresponding numbers are as shown below:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"ViroSceneView features\\n(3D rendering *without* AR / VR)\",\n    \"0-1\": \"API level 18, as restricted by [OpenGL ES 3.0](https://developer.android.com/guide/topics/graphics/opengl.html).\",\n    \"1-0\": \"ViroViewARCore features\\n(3D rendering with AR Core)\",\n    \"2-0\": \"ViroViewGVR features\\n(3D Rendering with VR)\",\n    \"1-1\": \"[API level 24](https://developers.google.com/ar/develop/java/enable-arcore) for an AR Required App.\",\n    \"2-1\": \"[API level 19 for cardboard compatibility.](https://developers.google.com/vr/develop/android/get-started)\\n[API level 25 for daydream compatibility.](https://developers.google.com/vr/develop/android/get-started)\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nYou can also target a wider range of Android SDK versions by building a hybrid application made out of mutually exclusive 3D ViroCore and 2D Android layout experiences. These applications delay the creation and use of AR / VR components and only inflates them on an AR / VR capable device. Else, on non-compatible devices, developers can then display their original 2D Android content as per normal. This drastically helps increase the application's audience size and reach.\n[block:api-header]\n{\n  \"title\": \"Additional Android Device Type Support\"\n}\n[/block]\nAn application's audience size, or the number of supported devices are ultimately defined by the Google Play Store. It filters out in-compatible devices, based on defined features in your manifest file. For example, devices without gyroscope sensors will be deemed incompatible if your app defines a gyroscope uses-feature in your manifest. For VR / AR, features like openGL, accelerometer and gyroscopes are required. \n\nHowever, for hybrid apps with exclusive 2D + optional AR experiences, there are situations where you may not want to use the gyroscope sensor at all - say, for your non-AR experiences on older devices. Currently, your app is ultimately 'blocked' from being downloaded by a larger audience with incompatible device types. For example, the gyroscope uses-feature tag required for AR then effectively blocks a large portion of your customers from downloading your app (those who don't have a gyroscope sensor), **even though your app is \"AR Optional\" and has an exclusive 2D layout experience!**\n\nThus, to get around this problem, we've provided you a list of **uses-feature overrides** that you can define in your manifest as shown below. These overrides effectively makes required features (like gyroscope / openGL / camera) optional instead. As a result, the Google Play store will then be able to identify a larger selection of compatible devices, where you can then dynamically determine AR/VR/Rendering capability and inflate your Android 2D or Viro Core 3D views as needed.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"When using Overriding <uses-feature> Tags:\",\n  \"body\": \"Note: Because Google Play no longer has the feature tags that are overwritten to filters apps by device compatibility, **developers are responsible for dynamically checking required uses-features that are needed for AR / VR rendering**. As such for every uses-feature that you override with, ensure that you dynamically check for this feature in Java before loading the desired AR / VR experience!\"\n}\n[/block]\nNote that you can also pick any set of overrides above that you desire:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<uses-feature android:glEsVersion=\\\"0x00030000\\\" android:required=\\\"false\\\" tools:node=\\\"remove\\\" tools:replace=\\\"required\\\" />\\n<uses-feature android:name=\\\"android.hardware.sensor.accelerometer\\\" android:required=\\\"false\\\" tools:replace=\\\"required\\\" />\\n<uses-feature android:name=\\\"android.hardware.sensor.gyroscope\\\" android:required=\\\"false\\\" tools:replace=\\\"required\\\" />\\n<uses-feature android:name=\\\"android.hardware.camera\\\" android:required=\\\"false\\\" tools:replace=\\\"required\\\" />\\n<uses-feature android:name=\\\"android.hardware.microphone\\\" android:required=\\\"false\\\" tools:replace=\\\"required\\\" />\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nHere's an example of the total number of supported devices that you can target on the Google Play store with the above overrides on a Viro Core Hello World AR project:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c1986af-Screenshot1.png\",\n        \"Screenshot1.png\",\n        1960,\n        344,\n        \"#3b6885\"\n      ]\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"android-distribution","type":"basic","title":"Distribution"}
To distribute your application follow the instructions for each respective platform. If you are distributing with Viro, please follow our [Attribution](doc:attribution) guidelines. Links provided below. Android Cardboard Distribution: https://developers.google.com/vr/distribute/cardboard/ Google Daydream Distribution: https://developers.google.com/vr/distribute/daydream/ Oculus Gear VR Distribution: https://developer3.oculus.com/documentation/publish/latest/ [block:api-header] { "title": "Building for Production" } [/block] First make sure you prepare your apk to be signed. More information on this can be found from the React native documentation: https://facebook.github.io/react-native/docs/signed-apk-android Once you have prepared your gradle files for a signed apk, you can build a production Android app that bundles your assets and code into an apk. To do this run the following from your project root android directory (ProjName/android) in terminal: To build for GVR or ARCore release: ```./gradlew assembleGvrRelease``` To build for Oculus Gear VR run: ```./gradlew assembleOvrRelease``` [block:api-header] { "title": "Updating Android project to Target API level 28" } [/block] The following steps are needed to update your Android project to Target API Level 28. This is required as of November 2018: Google Play Store no longer accepts APKs built using any Target older than 26. The instructions below are for Target 28. If due to other dependency issues you prefer Target 26 or 27 to Target 28, simply replace the Gradle version numbers below to what works best for your project setup. 1. Now open `android/build.gradle` file. * If not already present, add `google()` under `buildscript -> repositories` and `allprojects -> repositories` sections. * Under `buildscript -> dependencies`, change gradle classpath to `classpath 'com.android.tools.build:gradle:3.2.1'` 2. Open `android/gradle/wrapper/gradle-wrapper.properties` and update `distributionUrl` to `distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-all.zip` 3. Open `android/app/build.gradle` and make the following changes * Update compileSdkVersion to `compileSdkVersion 28` * Update buildToolsVersion to `buildToolsVersion '28.0.3'` * Add `flavorDimensions "platform"` under `buildToolsVersion`, if not already present. * In the `defaultConfig` section, update targetSdkVersion to `targetSdkVersion 28`. * In the `dependencies` section, update `compile 'com.android.support:appcompat-v7:25.0.0'` to `implementation 'com.android.support:appcompat-v7:28.0.0'` * **(Needed only if you *are* updating to `target 28`. Not needed for targets 26 or 27)** Update our AWS dependencies (needed for key validation) to the following ``` implementation 'com.amazonaws:aws-android-sdk-core:2.7.7' implementation 'com.amazonaws:aws-android-sdk-ddb:2.7.7' implementation 'com.amazonaws:aws-android-sdk-ddb-mapper:2.7.7' implementation 'com.amazonaws:aws-android-sdk-cognito:2.7.7' implementation 'com.amazonaws:aws-android-sdk-cognitoidentityprovider:2.7.7' ``` * Finally, change all `compile` tags in `dependencies` section to `implementation`. That's it! Sync your Android Project once these changes are done and start building. [block:api-header] { "title": "Targeting Older Android Builds" } [/block] Depending on you users and application, you might need to target and build with older versions of the Android SDK in Android Studio. To do so, simply lower the **minSdkVersion** version number as specified in the build.gradle file to the desired version. You will also need to inform Android about the version override in your Android manifest file with the **overrideLibrary* tag: [block:code] { "codes": [ { "code": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<manifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\n package=\"com.example.virosample\">\n \n \t<!-- Required to read the paired viewer's distortion parameters -->\n <uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>\n ... other permissions ...\n \n <!-- Perform our override here -->\n <uses-sdk tools:overrideLibrary=\"com.viro.renderer\"/>", "language": "xml" } ] } [/block] Depending on the features that you want to use in your application, there is also a minimum sdk version number to which you can lower the minSdkVersion towards for them to function properly. These features and their corresponding numbers are as shown below: [block:parameters] { "data": { "0-0": "ViroSceneView features\n(3D rendering *without* AR / VR)", "0-1": "API level 18, as restricted by [OpenGL ES 3.0](https://developer.android.com/guide/topics/graphics/opengl.html).", "1-0": "ViroViewARCore features\n(3D rendering with AR Core)", "2-0": "ViroViewGVR features\n(3D Rendering with VR)", "1-1": "[API level 24](https://developers.google.com/ar/develop/java/enable-arcore) for an AR Required App.", "2-1": "[API level 19 for cardboard compatibility.](https://developers.google.com/vr/develop/android/get-started)\n[API level 25 for daydream compatibility.](https://developers.google.com/vr/develop/android/get-started)" }, "cols": 2, "rows": 3 } [/block] You can also target a wider range of Android SDK versions by building a hybrid application made out of mutually exclusive 3D ViroCore and 2D Android layout experiences. These applications delay the creation and use of AR / VR components and only inflates them on an AR / VR capable device. Else, on non-compatible devices, developers can then display their original 2D Android content as per normal. This drastically helps increase the application's audience size and reach. [block:api-header] { "title": "Additional Android Device Type Support" } [/block] An application's audience size, or the number of supported devices are ultimately defined by the Google Play Store. It filters out in-compatible devices, based on defined features in your manifest file. For example, devices without gyroscope sensors will be deemed incompatible if your app defines a gyroscope uses-feature in your manifest. For VR / AR, features like openGL, accelerometer and gyroscopes are required. However, for hybrid apps with exclusive 2D + optional AR experiences, there are situations where you may not want to use the gyroscope sensor at all - say, for your non-AR experiences on older devices. Currently, your app is ultimately 'blocked' from being downloaded by a larger audience with incompatible device types. For example, the gyroscope uses-feature tag required for AR then effectively blocks a large portion of your customers from downloading your app (those who don't have a gyroscope sensor), **even though your app is "AR Optional" and has an exclusive 2D layout experience!** Thus, to get around this problem, we've provided you a list of **uses-feature overrides** that you can define in your manifest as shown below. These overrides effectively makes required features (like gyroscope / openGL / camera) optional instead. As a result, the Google Play store will then be able to identify a larger selection of compatible devices, where you can then dynamically determine AR/VR/Rendering capability and inflate your Android 2D or Viro Core 3D views as needed. [block:callout] { "type": "danger", "title": "When using Overriding <uses-feature> Tags:", "body": "Note: Because Google Play no longer has the feature tags that are overwritten to filters apps by device compatibility, **developers are responsible for dynamically checking required uses-features that are needed for AR / VR rendering**. As such for every uses-feature that you override with, ensure that you dynamically check for this feature in Java before loading the desired AR / VR experience!" } [/block] Note that you can also pick any set of overrides above that you desire: [block:code] { "codes": [ { "code": "<uses-feature android:glEsVersion=\"0x00030000\" android:required=\"false\" tools:node=\"remove\" tools:replace=\"required\" />\n<uses-feature android:name=\"android.hardware.sensor.accelerometer\" android:required=\"false\" tools:replace=\"required\" />\n<uses-feature android:name=\"android.hardware.sensor.gyroscope\" android:required=\"false\" tools:replace=\"required\" />\n<uses-feature android:name=\"android.hardware.camera\" android:required=\"false\" tools:replace=\"required\" />\n<uses-feature android:name=\"android.hardware.microphone\" android:required=\"false\" tools:replace=\"required\" />", "language": "xml" } ] } [/block] Here's an example of the total number of supported devices that you can target on the Google Play store with the above overrides on a Viro Core Hello World AR project: [block:image] { "images": [ { "image": [ "https://files.readme.io/c1986af-Screenshot1.png", "Screenshot1.png", 1960, 344, "#3b6885" ] } ] } [/block]