For Android

Integration Steps

To integrate DuopenGeofence into your Android project, follow these steps:

1. Adding Credentials to Access the Library

To ensure your project can access the DuopenGeofence library, update your settings.gradle file with the required credentials and Maven repository configuration.

Make sure the dependencyResolutionManagement block is properly configured as follows:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()       // Standard Google repository
        mavenCentral() // Central repository for dependencies
        maven {
            // Maven repository for Duopen Geofence library
            name = "duopen-geofence-android"
            url = uri("https://maven.pkg.github.com/duopen-tecnologia/duopen-geofence-android")
            credentials {
                // Replace <YOUR_CREDENTIAL> with your actual password or token
                username = "duopen-tecnologia"
                password = "<YOUR_CREDENTIAL>"
            }
        }
    }
}

NOTE:

1. Replace <YOUR_CREDENTIAL> with the actual password or token provided by us.

2. Avoid hardcoding sensitive credentials directly into your codebase. Instead, use secure methods such as environment variables or a secrets management tool.

2. Add the Duopen Geofence Library

Include the following line in the build.gradle file of your app:

implementation("io.github:duopen.geofence.android:1.0.0")

3. Add Required Dependencies

The following libraries are also necessary for DuopenGeofence to works correctly. Add them to the build.gradle file:

implementation("com.google.android.gms:play-services-location:21.0.1")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.7.3")
implementation("com.squareup.okhttp3:okhttp:4.11.0")
implementation("androidx.security:security-crypto:1.1.0-alpha06")

4. Required Permissions

The library requires specific permissions to works. These permissions must be explicitly requested and granted by the user:

• ACCESS_FINE_LOCATION: To get the precise location when the app is active.

  • NOTE: Users must select the Fine or Precise option. We advise to use popups or some sort of modal to guide the user before the permission request.

• ACCESS_BACKGROUND_LOCATION: To detect geofence transitions in the background.

  • NOTE: Users must select the Allow all the time option. We advise to use popups or some sort of modal to guide the user before the permission request.

Additional permissions, which are automatically included in the AndroidManifest.xml during the library’s integration, include:

• INTERNET: Ensures connectivity for the main app.

• RECEIVE_BOOT_COMPLETED: Detects device restarts to maintain geofence functionality.

NOTE: Since the library’s permissions are merged into the main app’s AndroidManifest.xml, manual addition is unnecessary.

5. Library Functions

Necessary Imports:

import io.github.duopen.geofence.DuopenGeofence
import io.github.duopen.geofence.utils.Mode

The library has only one function accessible by the developer. After permissions are granted, initialize the library using:

DuopenGeofence(context).builder(accessKey, "12212212212", Mode.DEBUG)

Parameters:

• context: Preferably the MainActivity context.

• accessKey: A UUID provided for each application, mapping geofences to specific locations.

• CPF: A unique identifier for logged users (e.g., “12345678900”).

  • NOTE: Please ensure that you are passing the correct user's CPF stored in your app.

• Mode:

  • Mode.DEBUG: Sends location transitions to test endpoints (data not stored).

  • Mode.RELEASE: Stores data in the production database. Ensure Mode.RELEASE is used for production builds.

  • NOTE: Please ensure that if you are running on an emulator, use the mode.DEBUG parameter.

Return:

• The function does not have a return

---

Example of Usage

Developers must ensure users grant both FINE and BACKGROUND location permissions.

Below is an implementation example in a generic MainActivity:

package com.example.testapp

import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.media3.common.util.Log
import io.github.duopen.geofence.DuopenGeofence
import io.github.duopen.geofence.utils.Mode


class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Request FINE location permission
        if (ActivityCompat.checkSelfPermission(
                this,
                Manifest.permission.ACCESS_FINE_LOCATION
            ) != PackageManager.PERMISSION_GRANTED
        ) {
            Log.d("MainActivity", "Requesting ACCESS_FINE_LOCATION")
            ActivityCompat.requestPermissions(
                this,
                arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
                LOCATION_PERMISSION_REQUEST_CODE
            )
        } else {
            // Request BACKGROUND location permission
            if (ActivityCompat.checkSelfPermission(
                    this,
                    Manifest.permission.ACCESS_BACKGROUND_LOCATION
                ) != PackageManager.PERMISSION_GRANTED
            ) {
                Log.d("MainActivity", "Requesting ACCESS_BACKGROUND_LOCATION")
                ActivityCompat.requestPermissions(
                    this,
                    arrayOf(Manifest.permission.ACCESS_BACKGROUND_LOCATION),
                    BACKGROUND_LOCATION_PERMISSION_REQUEST_CODE
                )
            } else {
                // Initialize DuopenGeofence if permissions are granted
                DuopenGeofence(this).builder(accessKey, "12212212212", Mode.DEBUG)
            }
        }
    }

    private val accessKey = "<YOUR_ACCESS_KEY>"
    private val LOCATION_PERMISSION_REQUEST_CODE = 1001
    private val BACKGROUND_LOCATION_PERMISSION_REQUEST_CODE = 1002

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)

        when (requestCode) {
            LOCATION_PERMISSION_REQUEST_CODE -> {
                if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    Log.d("MainActivity", "ACCESS_FINE_LOCATION granted")

                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                        if (ActivityCompat.checkSelfPermission(
                                this,
                                Manifest.permission.ACCESS_BACKGROUND_LOCATION
                            ) != PackageManager.PERMISSION_GRANTED
                        ) {
                            Log.d("MainActivity", "Requesting ACCESS_BACKGROUND_LOCATION")
                            ActivityCompat.requestPermissions(
                                this,
                                arrayOf(Manifest.permission.ACCESS_BACKGROUND_LOCATION),
                                BACKGROUND_LOCATION_PERMISSION_REQUEST_CODE
                            )
                        }
                    }
                } else {
                    Log.d("MainActivity", "ACCESS_FINE_LOCATION not granted")
                }
            }
            BACKGROUND_LOCATION_PERMISSION_REQUEST_CODE -> {
                if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    Log.d("MainActivity", "ACCESS_BACKGROUND_LOCATION granted")
                    DuopenGeofence(this).builder(accessKey, "12212212212", Mode.DEBUG)
                } else {
                    Log.d("MainActivity", "ACCESS_BACKGROUND_LOCATION not granted")
                }
            }
        }
    }
}

Testing the Duopen Geofence Library in Android Studio Emulator

1. Enable GPS in the Android emulator.

2. Open the Device Manager in Android Studio and select the emulator.

3. In the 3 dots that appear on the top, click to access the Extended Controls > Location and set a location or route passing through the geofence.

4. Open Google Maps on the emulator to force geofence updates. Note that updates may take 5-10 minutes based on the user’s last known location.

• You will be able to see the logs like the following if everything is working:

  • EVENT ~ Location: test-location | CPF: 12312312312| Status: IN | Mode: DEBUG