Integrating with your Android app

The App Embed Component for Android is an AAR library that is imported into your Android Studio project. It provides a set of Activities that host the complete Zappar environment.

Looking to integrate our legacy Android Studio module rather than an AAR file? Check out the article on integrating the legacy Android Studio module.

Step by Step

1. Unzip the App Embed Component

The App Embed Component download is a zip file that contains:

zappar-release.aar. The embed component itself - this is what will be integrated into your app. The AAR file includes two additional dependencies - ExoPlayer and OkHttp. The zipped folder also includes a version without these dependencies in case you already use these in your project.

ZapparEmbedTest. An example Android Studio project that demonstrates the integration.

The first step is to unzip the contents into a folder of your choosing.

2. Copy zappar-release.aar into your Android Studio project's libs folder

Your project's main app module should have a libs folder - that's the best place to copy the AAR file.

The next steps take place in Android Studio so open your project if you haven't already done so.

3. Add the Zappar component as a dependency of your app's module

Open your app module's build.gradle file from the project navigator.

Add the following code before the dependencies section in the build.gradle file. If the file doesn't have a dependencies section, check that you're in your app module's build.gradle file rather than that of your entire project.

repositories {
    flatDir {
        dirs 'libs'
    }
}

That block of code tells Gradle to look in your app module's libs folder for external libraries.

The next step is to include the following line inside the dependencies block in the same build.gradle file:

dependencies {
    // ...

    // ARCore library
    implementation 'com.google.ar:core:1.8.0'

    compile(name:'zappar-release', ext:'aar')

    // ...
}

When adding the AR Core library, it is important to use version number 1.8.0 as in the above example. The embed component for Zappar uses this exact version. If you need to use a different version for any reason, please contact us at support@zappar.com.

4. Add your API key

Add the following tag inside the <application> block of your AndroidManifest.xml file:

<meta-data android:name="com.zappar.embed.API_KEY" android:value="your_api_key"/>

Replace your_api_key with the key we supplied you for this application. Note that the API key is tied to the package name of your app (e.g. com.example.myapp). If you change your package name you will have to request a new API key from us at support@zappar.com.

5. Update your Proguard Rules

If you use Proguard to minify release versions of your app, add the following entries to your Proguard configuration (e.g. your proguard-rules.pro file):

-dontwarn okio.**
-dontwarn javax.annotation.**
-dontwarn com.google.android.exoplayer.**
-dontwarn com.google.android.exoplayer2.**
-keep class com.google.android.exoplayer.** { *; }
-keep class com.google.android.exoplayer2.** { *; }
-keep class com.extrareality.** { *; }

6. Update your AndroidManifest.xml to allow legacy storage

On Android 10, when using SDK 29 it is necessary to include a configuration option to allow local saving of camera images eg for AR selfies or as part of an experience.

Use the following configuration in the application tag in the manifest file:

android:requestLegacyExternalStorage=“true”

7. At runtime, check that the device works with Zappar

While Zappar is supported on most devices running Android 2.3 and later, a small number of problematic devices are blacklisted. The embed component provides a function that can be used to ensure that the current device is compatible.

boolean isCompatible = ZapparEmbed.isCompatible(<<yourcontext>>);

8. Start the Zappar component

The component is launched using an Intent:

Intent i = new Intent(this, ZapparEmbed.getZapcodeClassForIntent());
startActivity(i);

This starts an Activity that manages the complete Zappar scanning/AR function.

Suggested Next Steps

With the component successfully launching in your app, you may wish to complete our Regression Test suite to ensure it works correctly.

The next article discusses the options for customizing the user interface of the Zappar component:

zapcode branded_zapcode i