.. title:: Getting Started on Android

Getting Started on Android
==========================

The Android Capture client aims to make it as simple as possible to add scanning functionality into
an Android application. It hides the complexity of the Android activity lifecycle by hooking into
it. If you use a non-standard application architecture or just want more explicit control over the
client and it's lifecycle, please refer to the :doc:`Java docs </getting-started>` and create and
manage an instance of :java:type:`CaptureClient` directly.

Install Companion App
---------------------
SocketMobile Companion app is required for the SDK to work. Click `here <https://play.google.com/store/apps/details?id=com.socketmobile.companion&hl=en_US&gl=US>`_ to download it from the Google Play Store

Add the SDK to your project
---------------------------

.. code-block:: groovy
   :caption: app/build.gradle
   :emphasize-lines: 3-5,9

   repositories {
       mavenCentral()
       maven {
           url "https://bin.socketmobile.com/repo/releases"
       }
   }

   dependencies {
       implementation 'com.socketmobile:capture-android:1.8.x'
   }

Provide your AppKey
-------------------
AppKey is required to integrate the SDK into your app. It is generated once and has no expiration.
You can get and manage your AppKeys in the Socket Mobile Developer portal `here <https://developers.socketmobile.com>`_.  
Log into the portal and click on the "My Applications" button.

.. code-block:: xml
   :caption: AndroidManifest.xml
   :emphasize-lines: 5-10

   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns:android="..." >
     <application android:label="..." >

       <meta-data
           android:name="com.socketmobile.capture.APP_KEY"
           android:value="..."/>
       <meta-data
           android:name="com.socketmobile.capture.DEVELOPER_ID"
           android:value="..."/>

     </application>
   </manifest>


Start Capture
-------------

You can set up capture in the ``onCreate`` method of either your ``Application`` or initial
``Activity``

.. code-block:: java
    :caption: MainActivity.java
    :emphasize-lines: 3,10-12

    import android.support.v7.app.AppCompatActivity;
    import android.os.Bundle;
    import com.socketmobile.capture.android.Capture;

    public class MainActivity extends AppCompatActivity {
      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_main)
          Capture.builder(getApplicationContext())
            .enableLogging(BuildConfig.DEBUG)
            .build();
      }
    }

Enable Cleartext Traffic
------------------------

.. note:: If your app targets Android 27 or lesser, this can be ignored.

Apps that target Android 28+ must enable cleartext traffic to localhost. If you do not already
have a network security configuration file, you will need to create one.

.. code-block:: xml
   :caption: AndroidManifest.xml
   :emphasize-lines: 4

   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns:android="..." >
     <application android:label="..."
         android:networkSecurityConfig="@xml/network_security_config"
         ...>

     </application>
   </manifest>

.. code-block:: xml
   :caption: res/xml/network_security_config.xml
   :emphasize-lines: 4-7

   <?xml version="1.0" encoding="utf-8"?>
   <network-security-config>
     <base-config cleartextTrafficPermitted="false" />
     <domain-config cleartextTrafficPermitted="true">
       <domain includeSubdomains="false">localhost</domain>
       <domain includeSubdomains="false">127.0.0.1</domain>
     </domain-config>
   </network-security-config>


Camera Scanning Using SocketCam
-------------------------------

CaptureSDK has an option to use the device camera as a barcode scanner and it is called SocketCam and supports basic scanning capapilites with what is called the SocketCam C820.
SocketCam devices behave like the physical barcode scanners. Use the :ref:`SocketCam` documentation on how to use the Camera.

Once SocketCam is integrated as a scanner in your application, you can switch to physical scanner with no code change or minimal code change depending on the type of scanner chosen.