Tutorial 1: Use the built-in scanner

In this tutorial, we will walk you through how to use the builtin scanner. The scanner screen opens the in phone camera with a scanning line overlaid on the camera view, indicating the app is actively querying for a match. Once a match is found, a result is returned with the URL payload which is opened by the builtin web viewer. Next, we will walk you through the steps to build this app. You will be amazed this sounds complex app can be built with 20 lines of code.

1. Create scanner app

Start Android Studio to create a new Android project. Type "Scanner" as the Application Name. Set API 19 as the minimal supported SDK. At the "Add an Activity to Mobile" page, select "Empty Activity". Leave the Activity Name and Layout Name as it is, click "Finish"!

2. Add dependency

Add aiqkit as a dependency in app/build.gradle

app/build.gradle


dependencies {
    implementation "tech.aiq:aiqkit:0.9.4"
}
                    

3. Add AppID and Secret

Append the following 3 lines to your project's gradle.properties:

gradle.properties:


AIQ_APP_ID=5f61ed2c19e734ca4cf29aa7413dc2ec5bd7e1fb3882cdb1db
AIQ_APP_SECRET=15d674e0308a6d05838ca10b64c087d6287b45406137a459581a4b7bc6c1f445
AIQ_APP_SERVER=
                    

The AppId and Secret used here are strictly for demo purpose. The AIQ engine segregates the search database based on the AppID. This given sample AppID has its pre-ingested content showing here. This can help you quickly build the sample app and start scanning with some meaningful response. Otherwise, you'll need to ingest your own images using your account and AppID before you can do some search.

The AIQ_APP_SERVER property gives you a chance to override AIQ's default end points. AIQ offers two server end points out of the box. You can get them with AIQKit.getServiceEndPoint(AIQKit.ServiceType.STAG) or AIQKit.getServiceEndPoint(AIQKit.ServiceType.PROD) in your code or you can define your custom end points here directly if you use another address, which is currently impossible. As a rule of thumb, you should leave this property empty and retrieve the service end points in your code, instead. Note a AppID only works in one server type, either Staging or Production. For the demo AppID used here, it is created in Staging system.

Now you have defined the properties, next you have to import them to Java land via Gradle in app/build.gradle:

app/build.gradle


defaultConfig {
        ...

        buildConfigField('String', 'AIQ_APP_ID', "\"${AIQ_APP_ID}\"")
        buildConfigField('String', 'AIQ_APP_SECRET', "\"${AIQ_APP_SECRET}\"")
        buildConfigField('String', 'AIQ_APP_SERVER', "\"${AIQ_APP_SERVER}\"")
        ...
}
                    

4. Define and use the layout

The app has one Activity, which shows a button and a short description text. A click on the button will start the scanner. The following is a screenshot of the app:

and the corresponding layout xml:

layout.xml


<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@color/orange"
    android:gravity="center"
    android:orientation="vertical"
    tools:context="com.example.scanner.MainActivity">

    <Button
        android:id="@+id/button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:padding="5dp"
        android:onClick="OnClick"
        android:text="Open Scanner"
        android:textColor="@color/orange" />

    <TextView
        android:id="@+id/textView"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="20dp"
        android:layout_marginLeft="20dp"
        android:layout_marginRight="20dp"
        android:text="Open AIQ Scanner to start search!"
        android:textColor="@color/white"
        android:textSize="18sp" />

</LinearLayout>

                    

Note the Button's OnClick event is registered to a OnClick function, which is defined in the MainActivity class:

MainActivity


public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }

    public void OnClick(View view) {
        AIQKit.startScanner(this);
    }
}
                    

OnClick() calls the AIQKit.startScanner() function to start the builtin scanner, and that's all you need to do to use the scanner.

5. Initialize the SDK

Invoking AIQKit.startScanner() starts the builtin scanner, but before that, you need to initialize the SDK. Generally, you should initialize the SDK once during your application's entire life cycle. A good place to initialize the SDK is in your Application class's OnCreate() method. Let's define a ScannerApplication class:

ScannerApplication


public class ScannerApplication extends Application {
 
    private static final String TAG = ScannerApplication.class.getSimpleName();
 
    @Override
    public void onCreate() {
        super.onCreate();
 
        Log.d(TAG, "ScannerApplication Started");
 
        String serverUrl = BuildConfig.AIQ_APP_SERVER;
 
        if (TextUtils.isEmpty(serverUrl)) {
            serverUrl = AIQKit.getServiceEndPoint(AIQKit.ServiceType.STAG);
            Log.d(TAG, "Using AIQ staging server");
        }
 
        //initialize aiqkit
        AIQKit.init(this, BuildConfig.AIQ_APP_ID, BuildConfig.AIQ_APP_SECRET, serverUrl);
        Log.d(TAG, "Initialized AIQKit SDK");
    }
}
                    

6. Tweaking the Manifest

If you encounter build errors, it might due to the aiqkit SDK also defines AppTheme. You can use "tools:replace" attribute of <Application> to address this conflict:

AndroidManifest


<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.scanner">
 
    <application
        android:name=".ScannerApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme"
        tools:replace="android:theme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>
                    

7. Test the app

Now the app is ready to build. Because the demo AppID is tied to these ingestions, you can point your camera at any ingestion on the page. If a match is not returned immediately, make sure your camera is properly aligned with one ingestion image, and focused on it. Remember that the app needs camera permission, so please grant it using the "settings".