Installation Instructions

Suggest Edits

Installation instructions

If you are starting a new project, please consider using our Starter Kit as a basis for your app.

The steps below are for manually installing and linking the library to an existing React Native project. We do not yet support auto-linking.

👍

We support Expo via plugins

See our Integrating with Expo Projects for more.

Install

NPM

$ npm install --save @viro-community/react-viro

Yarn

$ yarn add @viro-community/react-viro

Linking (You must do this - we do not support auto-linking)

If you're unsure about which file to edit or where to put specified the lines, we have added links to how this is done in our starter-kit repo.

iOS Linking (You must do this - we do not yet support auto-linking)

1. Add the following lines to your ios/Podfile below use_react_native!(:path => config["reactNativePath"]):

pod 'ViroReact', :path => '../node_modules/@viro-community/react-viro/ios/'
pod 'ViroKit', :path => '../node_modules/@viro-community/react-viro/ios/dist/ViroRenderer/'

See this example

2. Install the iOS native pods by running:

$ npx pod-install

or inside the ios directory...

$ pod install

3. If you are going to be doing any AR then you will need to request permissions for using the camera in the ios/APP_NAME/info.plist by adding the following:

    <key>NSCameraUsageDescription</key>
    <string>The camera is needed for AR functionality</string>

The string can be more appropriate to the needs of your app.

See an example here.

4. You're done! You can now run npx react-native ios.

Remember, if you are using AR, you need to run on a real device.

Android Linking (You must do this - we do not yet support auto-linking)

1. In your android/build.gradle Bump the minimum SDK version to at least 24, and the gradle plugin to at least 4.1.1:

buildscript{
  ext{
    ...
    minSdkVersion = 24
    ...
  }
  ...
  dependencies{
    classpath('com.android.tools.build:gradle:4.1.1')
  }
}

See an example here.

2. In your android/app/build.gradle Add the following lines to the dependencies section:

dependencies {
  implementation fileTree(dir: "libs", include: ["*.jar"])
  //noinspection GradleDynamicVersion

  implementation "com.facebook.react:react-native:+"  // From node_modules

  // Add these lines
  implementation project(':gvr_common')
  implementation project(':arcore_client')
  implementation project(path: ':react_viro')
  implementation project(path: ':viro_renderer')
  implementation 'com.google.android.exoplayer:exoplayer:2.7.1'
  implementation 'com.google.protobuf.nano:protobuf-javanano:3.0.0-alpha-7'

See an example here.

3. In your android/settings.gradle Add the following lines to the end:

include ':react_viro', ':arcore_client', ':gvr_common', ':viro_renderer'
project(':arcore_client').projectDir = new File('../node_modules/@viro-community/react-viro/android/arcore_client')
project(':gvr_common').projectDir = new File('../node_modules/@viro-community/react-viro/android/gvr_common')
project(':viro_renderer').projectDir = new File('../node_modules/@viro-community/react-viro/android/viro_renderer')
project(':react_viro').projectDir = new File('../node_modules/@viro-community/react-viro/android/react_viro')

See an example here.

4. In your android/gradle/wrapper/gradle-wrapper.properties set the distributionUrl to at least 6.5:

distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-bin.zip

See an example here.

5. Now add the Viro package to your MainApplication.java:

  • Add the following line to the end of the import list:

    import com.viromedia.bridge.ReactViroPackage;

  • Add the imported package inside the getPackages method:

    @Override
protected List<ReactPackage> getPackages() {
  @SuppressWarnings("UnnecessaryLocalVariable")
  List<ReactPackage> packages = new PackageList(this).getPackages();

  // Add this line
  packages.add(new ReactViroPackage(ReactViroPackage.ViroPlatform.valueOf("AR")));

  return packages;
}

    You can replace the string AR with one of the following depending on your needs: GVR, OVR_MOBILE, AR.

See an example here.

6. In your android/app/src/main/AndroidManifest.xml:

For AR

  • Ensure the <manifest> has the tools namespace schema:

    <manifest ... xmlns:tools="http://schemas.android.com/tools" ...>

  • Add the following line to the <application> node, this enables ARCore:

    <meta-data android:name="com.google.ar.core" android:value="optional" />

    Note: If you want to restrict your app to ARCore-only devices, set the android:value to "required"

  • Add the camera permission to the <manifest> node below other permissions:

    <uses-permission android:name="android.permission.CAMERA" />

    There are quite a few other camera-related permissions and features you might also want to specify, depending on your app:

    <!-- You may need these if doing any screen recording from within the app -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- Other camera related features -->
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false" tools:replace="required"/>
<!-- Specifying OpenGL verison or requirements -->
<uses-feature android:glEsVersion="0x00030000" android:required="false" tools:node="remove" tools:replace="required" />
<!-- Usage of accelerometer and gyroscope -->
<uses-feature android:name="android.hardware.sensor.accelerometer" android:required="false" tools:replace="required" />
<uses-feature android:name="android.hardware.sensor.gyroscope" android:required="false" tools:replace="required" />
For VR

  • If your app supports Cardboard or Daydream, you should add them as a category to the intent-filter in your activity:

    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    <!-- Add the following line for cardboard -->
    <category android:name="com.google.intent.category.CARDBOARD" />
    <!-- Add the following line for daydream -->
    <category android:name="com.google.intent.category.DAYDREAM" />
</intent-filter>

  • To support GearVR, you need to add the following under the <application> node:

    <meta-data android:name="com.samsung.android.vr.application.mode" android:value="vr_only"/>
For API level 30 or above
 If you are targetting API Level 30 or above, make sure to add the following lines to the `<manifest>`:
 ```xml
 <queries>
     <package android:name="com.google.ar.core" />
 </queries>
 ```
Optional - when debugging

Add the following line as an attribute on the <application> node. This should only used when debugging and is not recommended for production (you may want to inject the value using manifestPlaceholders set for specific build types).

<application
    android:usesCleartextTraffic="true"
    ...

See an example here. This example is for AR only.

7. You're done! You can now run npx react-native run-android to upload the app to your device.

Troubleshooting

  • It doesn't work on my iOS simulator!

    AR does not work on iOS simulators. If you are getting an error that looks like:

    ARWorldTrackingConfiguration setAutoFocusEnabled: unrecognised

    that is expected. Sorry!

    See running-on-device in the official react-native docs.

Updated over 1 year ago