Gradle Configuration

Open the file build.gradle file of the application module (not the main project) on Android Studio. Add the following lines to import geouniq url repository

android {
    //...
	repositories {
	    maven { url "https://mymavenrepo.com/repo/PzY5Lw6PNZ938XDfVtzf/" }
    }
}

Add the following dependency

dependencies{
    implementation 'com.geouniq.android:c4w-location-sdk:x.y.z'
}

Replace x.y.z with a specific version of library that you can find here

Manifest Configuration

The library already declare the basic permissions that needs, if your app meets the Google Play Store policies for background location, make sure you've declared permission to access background location:

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

ProGuard Configuration

The library already contains its ProGuard configuration file, which will be merged with your application's during the build process.

Providing the Mobile Key

The Mobile Key generated for your app when you configured your project (see here) must be provided as a string resource with name "geouniq_mobile_key".

This can be done by putting the following line into the Gradle build script of your app (build.gradle file of your app module)

defaultConfig {
    //...
    it.resValue("string", "geouniq_mobile_key", "YOUR_MOBILE_KEY")
}

It could be convenient to set a different value for the debug and the relase build types.

Note that the certificates used for the two build types are generally different, and thus their SHA1 fingerprint will be different. For this reason, you should create two different Client Apps, one for the debug and one for the release build, each with its own fingerprint (see Project Configuration). A common solution is to create two different projects, one for test and one for production, and create an Android Client App on each project, using the debug fingerprint for the test project and the release fingerprint for the production project.

buildTypes {
    release {
        //...
        it.resValue("string", "geouniq_mobile_key", "YOUR_PRODUCTION_MOBILE_KEY")
    }
    debug {
        //...
        it.resValue("string", "geouniq_mobile_key", "YOUR_TEST_MOBILE_KEY")
    }
}

Initialize SDK

Before initializing the SDK, the below must be imported.

import com.geouniq.android.GeoUniq;

After import, add the below code under the Application class onCreate() method. The SDK must be enabled before calling any of the other SDK methods.

GeoUniq.getInstance(context).enable()

As soon as the SDK starts for the first time, a Device ID is assigned to that specific installation of your app.

The Device ID assigned to an installation might change in case of rare events, for example if the local storage of the device gets erased.

The SDK provides two different ways to obtain the Device ID.

Getting the Device ID through a Device ID listener

The first method to obtain the Device ID is to set a IDeviceIdListener, as shown in the example below. When a listener is set, the SDK immediately returns the Device ID through the onDeviceIdAvailable() callback if the Device ID is already available. Otherwise, it will call the callback method as soon as the ID is obtained.

The best practice for an app that want to collect on a backend systems the Device ID assigned to each installation, is to set a IDeviceIdListener each time it starts. The mobile app would receive the Device ID each time and should always send it to the backend system. Then, the backend system should overwrite any previously stored value if the new received value is different.

public class MainActivity extends Activity {

    private GeoUniq geoUniq;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.geoUniq = GeoUniq.getInstance(this);
        this.setDeviceIdListener();
    }

    /**
     * Sets a listener to received the ID assigned to this device
     */
    private void setDeviceIdListener(){

        this.geoUniq.setDeviceIdListener(new GeoUniq.IDeviceIdListener() {

            @Override
            public void onDeviceIdAvailable(String deviceId) {
                Log.d("GeoUniq", "Device ID received: "+deviceId);
            }
        });
    }
}

Getting the Device ID by calling an explicit class method

The second way is to call the GeoUniq.getDeviceId() method. This method returns the value of the Device ID if it has already been obtained or null if the Device ID has not been obtained yet.

The method GeoUniq.getInstance(context).resetDeviceId() reset the Device Id by invoking a new device registration.

The locations of interest, such as home and work locations, are places identified based on the visits detected by the SDK.

Initialize Users

In order to track geofencing events, you need to initialize a user in your Cloud4Wi account.

Once both the WiFi and Location SDKs are installed you can use the following snippet to initialize the customer in Cloud4Wi as soon the deviceId is assigned to the phone. This function will initialize an anonymous user without any additional attribute or personal data associated.

The SDK can be enabled and disabled at runtime. To make GeoUniq SDK start, you need to enable it by calling the method GeoUniq.enable() at least once.

You might do that into the main activity of your app, as in the example below.

Once enabled, the SDK will not stop until you disable it by calling GeoUniq.disable(). That is, it will keep performing automatic operations, such as tracking the device position, even after a device reboot or an update of the app. Disabling the SDK at runtime is useful if you want the SDK to stop completely. For example, you could remotely control a configuration parameter of your app to stop the SDK for all or some of your installations.

If you simply don't want GeoUniq to keep collecting location data for a specific User, you can do that without completely disabling the SDK (see ). This way you can still exploit the mobile-side functionalities that the SDK provides without having GeoUniq collecting data for the specific user

For the SDK to be able to accomplish its main task, that is tracking the device position, the following requirements must be met:

• The foreground location permission must be granted to the app

• The background location permission must be granted to the app, if it meets the Google Play Store policies for background location

• The location functionality must be enabled on the device

• Google Play Services must be installed on the device (almost always met)

The SDK provides a simple way for checking all the requirements and optionally solve the related issues. Solving an issue generally implies showing an alert to the User. Depending on the specific requirement, a different alert will be shown.

The example below shows hot to check for all requirements and solve them. In the example, the check is performed on the onStart() method of the main activity

3.1.5 Release notes (24-06-2024)

Fixed

• Minor bug fix.

3.1.4 Release notes (18-06-2024)

Enhancements

• Added support to Android 14

Fixed

• Fixed proguard rule that prevent the obfuscation of client App.

• Removed the static permission ACTIVITY_RECOGNITION.

3.1.0 Release notes (07-02-2024)

Enhancements

• The SDK now support play-services-location library versions higher 20.0.x.

Fixed

• Fixed proguard rule that prevent the obfuscation of client App.

3.0.3 Release notes (05-09-2023)

Enhancements

• Added trigger geofence when enter for the first time

• Added API resetDeviceId()

• Now you can change the base API url declaring the meta data

  Copy

  com.geouniq.geo_api_base

3.0.2 Release notes (26-07-2023)

Fixed

• Removed fingerprint validation SDK side

3.0.1 Release notes (22-04-2022)

Fixed

• Fixed bug in the trigger manager that caused an error when updating the remote trigger list

3.0.0 Release notes (08-04-2022)

Enhancements

• Added engine that allow the SDK to identify "Locations Of Interest" as "Home Location" and "Work Location"

• Added engine that manage Triggers set by remote

Get Work Location

Allows to get the work location calculated for this device. Return a WorkLocation object if work location is available or null otherwise.

GeoUniq.getInstance(context).getWorkLocation()

Register Work Location listener

Sets the listener class that will receive updates when the work location changes. The listener must be impIement the IWorkLocationListener interface.

GeoUniq.getInstance(context).registerWorkLocationListener(listener)

Unregister Work Location listener

Remove work location updates for the listener.

GeoUniq.getInstance(context).unregisterWorkLocationListener(listener)

Get Home Location

Allows to get the home location calculated for this device. Return an HomeLocation object if home location is available or null otherwise.

GeoUniq.getInstance(context).getHomeLocation()

Register Home Location Listener

Sets the listener class that will receive updates when the home location changes. The listener must be impIement the IHomeLocationListener interface.

GeoUniq.getInstance(context).registerHomeLocationListener(listener)

Unregister Home Location listener

Remove home location updates for the listener.

GeoUniq.getInstance(context).unregisterHomeLocationListener(listener)

To initialize the framework and allow it to collect data in the background it is necessary to add this call in the didFinishLaunchingWithOptions method (this method don't start the tracking engine)

/* ------ AppDelegate.swift ------ */

//importing the framework
import GeoUniq

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    let _ = GeoUniq.sharedInstance()

    return true
}

/* ------ AppDelegate.m ------ */

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [GeoUniq sharedInstance];

    return YES;
}

Installation

CocoaPods

Add pod 'c4w-location-sdk' to your Podfile and run pod install. More details CocoaPods here.

Swift Package Manager

Repository: https://github.com/Cloud4Wi-Create/iOS-LocationSDK-SwiftPackage

Before you start

Create projects and apps in your console and get your mobile key

Step 1: SDK integration

CocoaPods

Add pod 'c4w-location-sdk' to your Podfile and run pod install. More details CocoaPods here.

For other integration methods see here

Step 2: Project initialization

Mobile key

Add the following key to Info.plist file (String value) with the corresponding value (that you obtained when added your app to your project)

<key>GUMobileKey</key>
<string>'your-mobile-key'</string>

Location usage keys

1. Add the following keys to Info.plist file (String value), the corresponding values will be shown to the user by iOS

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We would like to access your locations</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We would like to access your locations</string>

Step 3: SDK enable

Inizialize

To initialize the framework and allow it to collect data in the background it is necessary to add this call in the didFinishLaunchingWithOptions method (this method don't start the tracking engine)

//Swift
/* ------ AppDelegate.swift ------ */

//importing the framework
import GeoUniq

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    let _ = GeoUniq.sharedInstance()

    return true
}

//Objective C
/* ------ AppDelegate.m ------ */

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [GeoUniq sharedInstance];

    return YES;
}

Start

To start the tracking engine call enable method.

Example:

//Swift
/* ------ AppDelegate.swift ------ */

//importing the framework
import GeoUniq

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    GeoUniq.sharedInstance().enable()

    return true
}

//Objective C
/* ------ AppDelegate.m ------ */

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [[GeoUniq sharedInstance] enable];

    return YES;
}

The method GeoUniq.sharedInstance().getDeviceId() return the id relative to the device if it has been registered, nil otherwise.

The method GeoUniq.sharedInstance().resetDeviceId() reset the Device Id by invoking a new device registration.

The locations of interest, such as home and work locations, are places identified based on the visits detected by the SDK.

Get home location

Set home location listener

where ClassTest is conform to protocol GUHomeLocationListener:

Remove home location listener

Get home location listeners

Remove home location listeners

Project settings

Mobile key

Add the following key to Info.plist file (String value) with the corresponding value (that you obtained when added your app to your project)

Location usage keys

1. Add the following keys to Info.plist file (String value), the corresponding values will be shown to the user by iOS

If your app supports iOS add

1. Add the following key to Info.plist file (String value), it will be used to show a popup to the user before the provided by iOS. Only if the user accepted this first popup we request the permission to iOS.

Background fetch

In order to obtain a greater number of positions we suggest to enable this feature. To do this carry out these two steps:

1. Select your project -> Select your target -> Select 'Signing & Capabilities' tab -> tap on '+ Capability' -> select 'Background Modes' -> check 'Background fetch'

2. In AppDelegate add this code:

App Tracking Transparency

iOS 14 introduced the permission request to get the device's IDFA. In this regard, we have introduced two methods in our framework.

The first one checking the permission status:

And the second one that makes the request and returns the user's choice:

It is possible to use these methods but also the methods provided directly by iOS. There is no need to communicate to our framework the outcome of the permission. Invoke the request method as soon as possible. For example right after the enable.

Important: Before invoking the method for the request (both Geouniq and iOS) it is necessary to insert the key in the plist

Initialize Users

In order to track geofencing events, you need to initialize a user in your Cloud4Wi account.

Once both the WiFi and Location SDKs are installed you can use the following snippet to initialize the customer in Cloud4Wi as soon the deviceId is assigned to the phone. This function will initialize an anonymous user without any additional attribute or personal data associated.

To start the tracking engine call enable method. You can do that into the didFinishLaunchingWithOptions method. It is possible to enable directly the tracking engine when the initialize method is called. Once enabled, the SDK will not stop until you disable it by calling GeoUniq.sharedInstance().disable() If the application does not have the permissions or has not yet requested them, the enable method will request them.

Xcode

13.3

Swift

5.2 with "Build Libraries for Distribution" enabled (in case of updating the swift version of the app it isn't necessary to update the framework).

C4w-location-sdk

3.0.0 - Changelog

3.0.9 Release notes (29-06-2023)

Improvement

• The geofence entry event is triggered in all conditions ( even when the user downloads and installs the app and he is inside the geofence)

----------------------------------------------------------

3.0.8 Release notes (03-05-2023)

Improvement

• Return strings instead enum on tracking trasparency methods

----------------------------------------------------------

3.0.7 Release notes (17-04-2023)

Fix

• Fix on geofence paths

----------------------------------------------------------

3.0.6 Release notes (16-03-2023)

Fix

• Delete warning on location manager

----------------------------------------------------------

3.0.5 Release notes (08-02-2023)

Improvement

• Possibility to reset the device id (new registration)

----------------------------------------------------------

3.0.3 Release notes (30-05-2022)

Fix

• Delete background task warning

• Mitigation error FRONTBOARD 2343432205

----------------------------------------------------------

3.0.1 Release notes (22-04-2022)

Fix

• Minor bug fixes

----------------------------------------------------------

3.0.0 Release notes (11-04-2022)

Enhancements

• LOI

• Trigger

Fix

• Minor bug fixes

Get work location

//importing the framework
import GeoUniq

...

let work: GUWorkLocation? = GeoUniq.sharedInstance().getWorkLocation()

...

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"
...

GUHomeLocation* home = [[GeoUniq sharedInstance] getWorkLocation];

...

Set work location listener

//importing the framework
import GeoUniq

...

GeoUniq.sharedInstance().setWorkLocationListener(listener: ClassTest)

...

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"
...

[[GeoUniq sharedInstance] setWorkLocationListenerWithListener:[ClassTest class]];

...

where ClassTest is conform to protocol GUWorkLocationListener:

/**
 *  Delegate to implement in order to receive callbacks for the work location updates
 */
@objc public protocol GUWorkLocationListener {
	
	/**
	 Public constructor
	 */
	@objc init()
	
	/**
	 Called when a new work location is detected
	 
	 - parameter work: Work location detected
	 */
	@objc func onNewWorkLocationDetected(work: GUWorkLocation) -> ()
}

Remove work location listener

//importing the framework
import GeoUniq

...

GeoUniq.sharedInstance().removeWorkLocationListener(listener: ClassTest)

...

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"
...

[[GeoUniq sharedInstance] removeWorkLocationListenerWithListener:[ClassTest class]];

...

Get work location listeners

//importing the framework
import GeoUniq

...

let workLocationListeners: [GUWorkLocation]? = GeoUniq.sharedInstance().getWorkLocationListeners()

...

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"
...

NSArray *listeners = [[GeoUniq sharedInstance] getWorkLocationListeners];

...

Remove work location listeners

//importing the framework
import GeoUniq

...

GeoUniq.sharedInstance().removeWorkLocationListeners()

...

//importing the framework
#import "GeoUniq/GeoUniq-Swift.h"
...

[[GeoUniq sharedInstance] removeWorkLocationListeners];

...