Developer Incentive Program

Add the Library using Android Studio — Adding .AAR Package

1. Open your existing project. Then, right-click the project folder and select Open Module Settings. (Figure 1)

Figure 1. Open module settings

2. In Module Settings window, click Dependencies. Then, select + and 2 JAR/AAR Dependency. (Figure 2)

Figure 2. Select + to add a JAR/AAR Dependency

3. In the Add Jar/Aar Dependency window, type the name of the path to add the .aar file in this sample “libs” and click OK. (Figure 3)

Figure 3. Add Jar/Aar Dependency

4. Now, click Apply and OK. (Figure 4)

Figure 4. Apply Dependency

5. Next, place (copy) the provided .aar file inside the generated directory: AppName/app/libs (Figure 5)

Figure 5.

6. Now you're ready to Sync the Project Files. Go to File --> Sync Project with Gradle Files . (Figure 6)

Figure 6. Sync Project Files

Add Services

Open your app's AndroidManifest.xml file, then add these services and receivers REQUIRED by our library.

Add the following services and receivers to the manifest:

<service 
    android:name="coelib.c.couluslibrary.plugin.SurveyService"   
    android:label="Survey Service"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:enabled="true"
    android:exported="true">
</service>     

<service 
    android:name="coelib.c.couluslibrary.plugin.SurveyServicePrev"   
    android:label="Survey Service"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:enabled="true"
    android:exported="true">
</service>     
    
    
<receiver android:name="coelib.c.couluslibrary.plugin.SurveyReceiver" 
    android:exported="true">       	
    <intent-filter>
	<action android:name="android.intent.action.BOOT_COMPLETED" />
    </intent-filter>
</receiver>

<receiver
    android:name="coelib.c.couluslibrary.plugin.NetworkChangeReceiver"
    android:label="NetworkChangeReceiver"
    android:exported="true">
    <intent-filter>
    	<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
	<action android:name="android.net.wifi.WIFI_STATE_CHANGED" />
    </intent-filter>
</receiver>

Initialize the Library in Android Studio — After Adding the .AAR Package

1. Open your app's MainActivity LAUNCHER file. Confirm that the package included the following imports*: (Figure 9)

Figure 9.
```
import coelib.c.couluslibrary.plugin.NetworkSurvey;
```
*Android Studio imports occur automatically. If you do not see this line of code in the MainActivity file, add it manually.

2. In the public class of your MainActivity, create the following global variable. (Figure 9b)

Figure 9b. (We declare NetworkSurvey globally, because it will be referenced more than once in the MainActivity).
```
private NetworkSurvey mySurvey;
```

3. Next, in the onCreate() method of your MainActivity, add the library declaration. (Figure 10)

Figure 10. Add the following code to the onCreate() method:

mySurvey = new NetworkSurvey(context);
mySurvey.runMeasuresLib();

4. Finally, in the onDestroy() method of your MainActivity, unregister the library. (Figure 10b)

Figure 10. Add the following code to the onDestroy() method:
```
mySurvey.unregister(this);
```

Example code results in MainActivity - impacting import, the onCreate() method, and onDestroy() method:

Only add highlighted code:
For more information about the NetworkSurvey function, see the documentation.

Using with AndroidX

If you've migrated to AndroidX, you will need to add the following dependencies in build.gradle of the app.

Dependencies needed to be added in build.gradle of the app:

dependencies {
	//... your current dependencies
	implementation "androidx.lifecycle:lifecycle-extensions:2.0.0" // for Android X
}

*Note: There are no minimum values that need to be set for compileSdkVersion, buildToolsVersion, and targetSdkVersion. All versions acceptable by google should work with this method.

Make sure both of the following Android Gradle plugin flags are set to true in your gradle.properties file:

// When this flag is set to true, the Android plugin uses the appropriate AndroidX library instead of a Support Library.	
android.useAndroidX=true	

// When this flag is set to true, the Android plugin automatically migrates existing third-party libraries to use AndroidX dependencies by rewriting their binaries. 	
android.enableJetifier=true

Using with the Android Support Library

If your app is still using the Android Support Library, you will need to add the following dependencies in build.gradle of the app.

Dependencies needed to be added in build.gradle of the app:

dependencies {
	//... your current dependencies
	implementation "android.arch.lifecycle:extensions:1.1.1"
}

*Note: There are no minimum values that need to be set for compileSdkVersion, buildToolsVersion, and targetSdkVersion. All versions acceptable by google should work with this method.

Add the Library using React Native

Tested using React Native v.0.49 using a min SDK (minSdkVersion — 16).

Add Files — Add .AAR & build.gradle

1. In your React Native project, go to the android folder, then open the settings.gradle file. (Figure 11)

Figure 11. android --> settings.gradle

2. Add the include code to your settings.gradle file:

```
include ':app', ':netperf-lib'
```

Example:

Save & close.

3. Go back to open the android folder in your React Native project. (Figure 12)

Figure 12.

4. Next, create a new folder and name it netperf-lib. (Figure 13)

Figure 13. Create a new folder called netperf-lib inside the android folder

5. Copy the provided .AAR file to the new netperf-lib folder. (Figure 14)

Figure 14. android --> netperf-lib --> netperf-lib.aar

6. Next, copy the build.gradle file to the same folder. (Figure 15)

Figure 15. android --> netperf-lib --> build.gradle

Add Dependencies

1. Go back to the android folder in your React Native project. (Figure 16)

Figure 16.

2. Next, open the app folder. (Figure 17)

Figure 17. android --> app

3. Open the build.gradle file. (Figure 18)

Figure 18. android --> app --> build.gradle

4. In build.gradle, find the dependencies code. Add the following line:

```
compile project(':netperf-lib')
```

Example dependencies code results in build.gradle:

Only add highlighted code:

Add Services

Open your app's AndroidManifest.xml file, then add these services and receivers REQUIRED by our library.

Add the following services and receivers to the manifest:

<service 
    android:name="coelib.c.couluslibrary.plugin.SurveyService"   
    android:label="Survey Service"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:enabled="true"
    android:exported="true"
></service>     

<service 
    android:name="coelib.c.couluslibrary.plugin.SurveyServicePrev"   
    android:permission="android.permission.BIND_JOB_SERVICE" />
    
<receiver android:name="coelib.c.couluslibrary.plugin.SurveyReceiver" >       	
    <intent-filter>
	<action android:name="android.intent.action.BOOT_COMPLETED" />
    </intent-filter>
</receiver>

<receiver
    android:name="coelib.c.couluslibrary.plugin.NetworkChangeReceiver"
    android:label="NetworkChangeReceiver" >
    <intent-filter>
    	<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
	<action android:name="android.net.wifi.WIFI_STATE_CHANGED" />
    </intent-filter>
</receiver>

<uses-library android:name="org.apache.http.legacy" android:required="false" />

Initialize the Library in React Native

1. Open the MainApplication LAUNCHER file in your React Native project. Add the following import :

import coelib.c.couluslibrary.plugin.NetworkSurvey;

Example PATH: yourApp/android/app/src/main/java/com/yourApp (exact path may be different for your project)

Example import code results in MainApplication:

Only add highlighted code:

2. In the public class section of your MainApplication, create the following global variable.

```
private NetworkSurvey mySurvey;
```

3. Next, in the onCreate() method of your MainApplication, add the library declaration. (Figure 19)

Figure 19. Add the following code to the onCreate() method:

mySurvey = new NetworkSurvey(this);
mySurvey.runMeasuresLib();

4. Finally, in the onDestroy() method of your MainApplication, unregister the library. (Figure 19b)

Figure 19b. Add the following code to the onDestroy() method:
```
mySurvey.unregister(this);
```

Example code results in MainApplication:

Only add highlighted code:

Add the Library Using Xcode with Swift — Adding .framework Package

1. Open your existing project in Xcode. Right-click the project folder to create a New Group folder under your main project. (Figure 1)
In this example, we’ve renamed the folder to Frameworks. (Figure 2)

Figure 1. Create a New Group Folder

Figure 2. Rename the folder to Frameworks

2. Next, drag and drop the provided framework file Netperf-lib-xxx.framework into your newly created Frameworks folder. (Figure 3)

Figure 3. Drag & drop framework file into your project

3. A pop-up will appear with these default options selected:

Copy items if needed

Create folder references

(Target project should be selected)

Once verified, click Finish. (Figure 4)

Figure 4. Verify values in pop-up window are selected

4. Now, select and highlight your project from the left-hand side. — Make sure your target is selected in the center window (under Targets) and the main window is on the General tab. (Figure 5)

Figure 5. Make sure your screen looks like the example below:

5. Take the Netperf-lib-xxx.framework framework from the left-hand window and drag and drop this into the Embedded Binaries section. (Figure 6)

Figure 6. Drag & drop framework into Embedded Binaries

6. Before proceeding, verify that the provided framework also appears under the Linked Frameworks and Libraries section. Set the status to Required if it is not already. (Figure 7)

Figure 7. Make sure framework appears as a Linked Framework

7. Now you’re ready to edit the ViewController. Select ViewController.swift from the left-hand menu to edit the ViewController class. (Figure 8)

Figure 8. Make sure framework appears as a Linked Framework

8. Then, add the following code to use the framework with location: (Figure 9)

Figure 9. Add code to ViewController class

    //  ViewController.swift
    
import UIKit 
import CoreLocation
import Netperf
    
class ViewController: UIViewController , CLLocationManagerDelegate {
    let locationManager = CLLocationManager() 
	override func viewDidLoad() {
	    super.viewDidLoad()
	    // Ask for Authorisation from the User
	    self.locationManager.requestAlwaysAuthorization()   
	    // // For use in foreground
	    self.locationManager.requestWhenInUseAuthorization()
        
        if CLLocationManager.locationServicesEnabled() {
                locationManager.delegate = self
                locationManager.desiredAccuracy = kCLLocationAccuracyBest 
                locationManager.startUpdatingLocation()
            }
        
            let mySurvey =  NetworkSurvey()  //Library use
            mySurvey.runLibrary(lc: locationManager) //Library use with Location
        }
    
    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
        if let location = locations.first {
            locationManager.desiredAccuracy = kCLLocationAccuracyBest
            locationManager.startUpdatingLocation()
            SharedLocation.shared.locationManager = locationManager
            SharedLocation.shared.location = location
        }
    }
}

9. If you wish to use the framework without location, add the following code instead: (Figure 10)

Figure 10. Add code to ViewController class (without location)

    //  ViewController.swift
    
    import UIKit 
    import Netperf
    
    class ViewController: UIViewController {
    	override func viewDidLoad() {
    	    super.viewDidLoad()
        
            let mySurvey =  NetworkSurvey()  //Library use
            mySurvey.runLibrary() //Library use without Location
        }
    }

10. Finally, add the following properties to your Info.plist file.** (Figure 11)

Figure 11. Add properties to Info.plist

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
<key>NSContactsUsageDescription</key>
<string>Our application needs to your contacts</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Program requires GPS</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Program requires GPS</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Program requires GPS</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Our application needs permission to write photos...</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Our application needs permission to read photos</string>

** If you followed Step 9 from above (using the framework without location) then list these properties in your Info.plist file:

//Info.plist without location

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
<key>NSContactsUsageDescription</key>
<string>Our application needs to your contacts</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Our application needs permission to write photos...</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Our application needs permission to read photos</string>

Add the Library Using Xcode with Objective-C — Adding .framework Package

1. Open your existing project in Xcode. Right-click the project folder to create a New Group folder under your main project. (Figure 1)
In this example, we’ve renamed the folder to Frameworks. (Figure 2)

Figure 1. Create a New Group Folder

Figure 2. Rename the folder to Frameworks

2. Next, drag and drop the provided framework file Netperf.framework into your newly created Frameworks folder. (Figure 3)

Figure 3. Drag & drop framework file into your project

3. A pop-up will appear with these default options selected:

Copy items if needed

Create folder references

(Target project should be selected)

Once verified, click Finish. (Figure 4)

Figure 4. Verify values in pop-up window are selected

4. Now, select and highlight your project from the left-hand side. — Make sure your target is selected in the center window (under Targets) and the main window is on the General tab. (Figure 5)

Figure 5. Make sure your screen looks like the example below:

5. Take the Netperf-lib-xxx.framework framework from the left-hand window and drag and drop this into the Embedded Binaries section. (Figure 6)

Figure 6. Drag & drop framework into Embedded Binaries

6. Before proceeding, verify that the provided framework also appears under the Linked Frameworks and Libraries section. Set the status to Required if it is not already. (Figure 7)

Figure 7. Make sure framework appears as a Linked Framework

7. Now you’re ready to Create a new Swift File. In the Xcode menu click File —> New —> File. This should display the following windows: (Figure 8, Figure 9, Figure 10)

Figure 8. Select the Swift file, then click Next

Figure 9. Save the file name to anything you like, then click Create

Figure 10. Click Create Bridging Header

*Note: Clicking Create Bridging Header will automatically create a new Bridging-Header.h file for you.

8. After creating your Swift file, find and highlight the file in the left-hand menu, which will allow you to edit the contents. To use the framework with location, add the following code to File_Name.swift. (Figure 11)

Figure 11. Add code to the new swift file

    //  File_Name.swift
    //  TestOC
    
    import Foundation 
    import Netperf
    import SystemConfiguration.CaptiveNetwork
    import CoreLocation
    
    @objc
    class netPerfWrapper:  NSObject , CLLocationManagerDelegate {
        @objc func startNetPerf(){ 
 
    	    print("USE LIB")
    	    let mySurvey =  NetworkSurvey() //Library use
    	    let locationManager =  CLLocationManager() 
    	    mySurvey.runLibrary(lc: locationManager) //Library use with location
    	    
        }
    }

9. If you wish to use the framework without location, add the following code instead: (Figure 12)

Figure 12. Add code to the new swift file (without location)

    //  File_Name.swift
    //  TestOC
    
    import Foundation 
    import Netperf
    
    @objc
    class netPerfWrapper:  NSObject {
        @objc func startNetPerf(){ 
 
    	    print("USE LIB")
    	    let mySurvey =  NetworkSurvey() //Library use
    	    mySurvey.runLibrary() //Library use without location
    	    
        }
    }

10. Then, edit the new Bridging Header file. Add the following code to the new File_Name.Bridging-Header.h file that now appears in the left-hand menu. (Figure 13)

Figure 13. Add code to the new Bridging Header file

//  Use this file to import your target's public headers that you would like to expose to Swift
//  Bridging-Header follows the format File_Name-Bridging-Header.h
    
    #import <UIKit/UIKit.h>
    
    @class netPerfWrapper; 
    
    @interface netPerfWrapper : NSObject
    
    -(void)startNetPerf;
    
    @end

11. Next, use the library in your AppDelegate.m file. Add the following code: (Figure 14)

Figure 14. Add code to the Objective-C AppDelegate file

                    	
    //  AppDelegate.m
    //  TestOC
    #import "AppDelegate.h"
    #import "TestOC-Swift.h". //  This should follow the structure ProjectName-Swift.h                 	
    @interface AppDelegate ()
    @property (nonatomic,  strong) netPerfWrapper *myTest;
    @end
    
    @implementation AppDelegate
    
    -(BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:
    (NSDictionary *)launchOptions {
    // Override point for customization after application launch
    
    if (self.myTest == nil){
        self.myTest = [[netPerfWrapper alloc] init];
    }
    
    [self.myTest startNetPerf];
    return YES;
}

12. Finally, add the following properties to your Info.plist file. ** (Figure 15)

Figure 15. Add properties to Info.plist. (Open as Source Code)

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
<key>NSContactsUsageDescription</key>
<string>Our application needs to your contacts</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Program requires GPS</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Program requires GPS</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Program requires GPS</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Our application needs permission to write photos...</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Our application needs permission to read photos</string>

** If you followed Step 9 from above (using the framework without location) then list these properties in your Info.plist file:

//Info.plist without location

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
<key>NSContactsUsageDescription</key>
<string>Our application needs to your contacts</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Our application needs permission to write photos...</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Our application needs permission to read photos</string>

Using the Library for Fine-Grained and Energy-Efficient Geolocation

You may use the library to improve battery efficiency and produce more accurate geolocation results than Android’s built-in LocationManager alone. Our location software utilizes the built-in network and GPS functions of the device, as well as applying an adaptive filter and prediction algorithm to ensure the highest possible location granularity with the lowest possible battery usage.

To use this capability, simply call the getLocation() method from your application as in the example below, and then use the native Android-compatible functions to obtain geocoding data from the resulting Location object. You’ll find that our library produces more accurate location data while managing battery performance better then the native location method alone.

Our library’s built-in LocationManager partly uses the Android LocationManager, but functions differently by polling the GPS less frequently to improve battery life, and by passing all data received through our advanced linear quadratic estimation algorithm, which takes into account velocity vectors and other data to predict and improve geolocation results. Our method is far more effective in position determination, and far more energy efficient than increasing the polling frequency of the built-in LocationManager’s GPS function.

For more technical details on our geolocation feature, see our FAQ answer below.

Add this code to use Geolocation:

Location testLocation = mySurvey.getLocation();

Obtain the latitude and longitude values like this:

testLocation.getLatitude();
testLocation.getLongitude();

Upgrading the Library

If you've received the latest library version, there's no need to go through all the previous steps again. Upgrading the library is straightforward, whether you're running your project with Android Studio or React Native. Here, we'll walk you through the process step-by-step.

Upgrade the Library using Android Studio

1. Open Android Studio to your existing project. Then, right-click the project folder and select Open Module Settings. (Figure 20)

Figure 20. Open module settings

2. In Module Settings window, select + in top corner to add the updated dependency module. (Figure 21)

Figure 21. Select + to add the updated module

3. Select Import .JAR/.AAR package, click Next. (Figure 22)

Figure 22.

4. Browse for the new .AAR file and hit Finish. (Figure 23)

Figure 23.

5. You should now see a list of all your dependencies. Select the old module dependency, and remove it by clicking on the — button. (Figure 24)

Figure 24.

6. Now add the new module dependency by clicking on the + button and selecting the latest release file. Then hit OK. (Figure 25 & 26)

Figure 25.
Figure 26.

7. Hit OK again to close out of the module settings window. Repeat these steps each time when upgrading to the latest release.

Upgrade the Library using React Native

1. In your React Native project, go to the android folder, then open the library folder*. (Figure 27)

Figure 27. *In the initial instruction, we named the library folder 'netperf-lib'

2. Next, remove the old module: the .AAR file. (Figure 28)

Figure 28. Move old .AAR file to trash

3. Now copy the new .AAR file to your library folder. (Figure 29)

Figure 29. Copy new .AAR file to 'netperf-lib'

4. Next, open the build.gradle file located in the same folder. (Figure 30)

Figure 30.

5. Edit the .AAR filename to match to the latest version release. (Figure 31)

Figure 31.

6. IMPORTANT: Confirm that the file name in your library folder match with the build.gradle reference. (Figure 32)

Figure 32. Confirm .AAR file names are the same

Repeat these steps each time when upgrading to the latest release.

Changes to the Manifest

+ Click to Expand

Permissions

The library will never ask the user for permissions, but it relies on some permissions to be enabled within your app and may also take advantage of additional functionality when permitted. The following lists the specific required and optional permissions that should appear in your app’s manifest file:

The following permissions are critical to the library’s functionality:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> 
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> 
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> 
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/> 
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE"/> 
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/> 
<uses-permission android:name="android.permission.INTERNET"/>

The library may also take advantage of the following additional permissions if available:

<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS"/> 	
<uses-permission android:name="android.permission.READ_PHONE_STATE"/> 
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> 
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/> 
<uses-permission android:name="android.permission.BLUETOOTH"/>

Application

Add the following attribute within your application section of the manifest:

android:usesCleartextTraffic="true"

Method Reference

Method	Description	Return Value
runMeasuresLib()	Activates the library	void
getLocation()	Returns the geolocation object	Location Object
isMeasuresLibRunning()	Returns TRUE if the library is running, FALSE otherwise	Boolean

Performance & Battery

Example Performance on Sony G8232 Device. (Figure 33)

Figure 33. Performance in terms of CPU, Memory and Network

Ask the user to ignore battery optimizations (to improve geolocation accuracy). (Figure 34)

Figure 34. Example method asking user to ignore battery optimizations

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    Intent intent = new Intent();
    String packageName = getPackageName();
    PowerManager pm = (PowerManager) getSystemService(POWER_SERVICE);
    
    if (!pm.isIgnoringBatteryOptimizations(packageName)) {
        intent.setAction(android.provider.Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS);
        intent.setData(Uri.parse("package:" + packageName));
        startActivity(intent);
    }
}

Automated Opt-Out

At any time, you may stop our software's data collection for a particular user and fully integrate this with your own opt-out mechanism. Assuming you are already regulation-compliant, you probably have an existing data collection opt-out mechanism as part of your comprehensive privacy policy. When a user elects to opt-out using your existing opt-out mechanism, simply add a few lines of code to your software that creates a secure POST request to "www.measurementsys.com/opt-out/" and include the following form elements:

TABLE OF REQUEST ELEMENTS

Element	Description	Required?
partner	Your app's unique package name (bundle ID), e.g., com.example.myapp (must match your real package name)	required
fname	The end-user's first name who wants to opt-out	required
lname	The end-user's last name who wants to opt-out	required
email	The end-user's email address who wants to opt-out (we will not send them any email, not even to confirm)	required
UNIQUE IDENTIFIERS (at least one valid unique identifier is required)
phone	The end-user's phone number	optional
idfa	The end-user's IDFA	optional
aaid	The end-user's AAID	optional
imei	The end-user's IMEI	optional
imsi	The end-user's IMSI	optional

An example POST looks like:

https://www.measurementsys.com/opt-out/?fname=Example&lname=User&email=user@example.com&partner=com.example.myapp&phone=12223334455

If the POST succeeds, you will receive a response as a JSON object with the 'Status' attribute set to 'SUCCEED' and a confirmation number you can store in the 'Confirmation' attribute, for example:

{
    "Confirmation": "20190523185058-471",
    "Status": "SUCCEED",
    "email": "user@example.com",
    "fname": "Example",
    "fullname": "Example User",
    "lname": "User",
    "optoutdate": "1558637458",
    "optoutprettydate": "Thu May 23 2019 18:50:58 +0000",
    "partner": "com.example.myapp",
    "phone": "12223334455"
}

If the POST fails, you will receive a response as a JSON object with the 'Status' attribute set to 'FAIL' and an explanatory message in the 'ReasonFailed' attribute, for example:

{
    "ReasonFailed": "At least one valid, unique identifier is required.",
    "Status": "FAIL",
    "email": "user@example.com",
    "fname": "Example",
    "fullname": "Example User",
    "lname": "User",
    "optoutdate": "1558638210",
    "optoutprettydate": "Thu May 23 2019 19:03:30 +0000",
    "partner": "com.example.myapp"
}

Frequently Asked Questions

Q: Will the library create pop-ups and/or ask the user for any permissions?

A: No, our software will utilize whatever permissions are already enabled for the app and will never interrupt your user and/or ask for additional permissions beyond what is already available in the app. Apps that already have certain permissions are therefore able to perform more tasks, thus they are more important to our program.

Q: Will the library use more battery or cause performance issues?

A: If you’re already using some location service and are replacing that with the library, you will likely see an improvement in battery utilization. If you’re not using location services, the amount of battery and performance consumed by the library will be negligible and we have provided graphs above that show its precise utilization.

Q: What if my app doesn't use background location, should I add the permission anyway?

A: If your app does not have critical functionality for background permissions, you should not add the background location permission —> ACCESS_BACKGROUND_PERMISSION. However, you should still use the fine-grained permissions for foreground location if your app uses location in the foreground. In this case, the framework would only use the location on foreground.

Q: How is the Geolocation feature technically different from Android’s built-in LocationManager?

A: Our geolocation determination software polls the device’s built-in GPS sensor less frequently and sends all data received from the GPS system through our advanced linear quadratic estimation algorithm, which takes into account velocity vectors and other data to predict and improve geolocation results. The algorithm continues to operate highly efficiently and when you request a Location object, instead of using the last data received by the GPS, the algorithm provides a location estimate that is highly accurate. Our method is far more effective in position determination, and far more energy efficient than increasing the polling frequency of the built-in LocationManager’s GPS function.

Our advanced mathematical filter is similar to those used in advanced navigational systems, such as inertial navigation systems. Instead of relying on data received from the sensors like Android’s built-in LocationManager, the sensor data merely seeds the algorithm and then the angular velocity is calculated and used to predict location outcomes, which creates a smoother track of location data even when sensor data is not being received frequently from the GPS. When GPS data is received (again less frequently), that data is used to further seed the algorithm which is self-adjusting as more data flows in from the sensors. Basically you’re getting more accurate (predictive) more frequent location updates (from the predictive algorithm itself) even though the Android GPS setting (LocationManager) is being called less frequently for updates, thereby saving battery.

Developer Incentive Program

About the Program

Add the Library using Android Studio — Adding .AAR Package

1. Open your existing project. Then, right-click the project folder and select Open Module Settings. (Figure 1)

2. In Module Settings window, click Dependencies. Then, select + and 2 JAR/AAR Dependency. (Figure 2)

3. In the Add Jar/Aar Dependency window, type the name of the path to add the .aar file in this sample “libs” and click OK. (Figure 3)

4. Now, click Apply and OK. (Figure 4)

5. Next, place (copy) the provided .aar file inside the generated directory: AppName/app/libs (Figure 5)

6. Now you're ready to Sync the Project Files. Go to File --> Sync Project with Gradle Files . (Figure 6)

Add Services

Open your app's AndroidManifest.xml file, then add these services and receivers REQUIRED by our library.

Initialize the Library in Android Studio — After Adding the .AAR Package

1. Open your app's MainActivity LAUNCHER file. Confirm that the package included the following imports*: (Figure 9)

2. In the public class of your MainActivity, create the following global variable. (Figure 9b)

3. Next, in the onCreate() method of your MainActivity, add the library declaration. (Figure 10)

4. Finally, in the onDestroy() method of your MainActivity, unregister the library. (Figure 10b)

Example code results in MainActivity - impacting import, the onCreate() method, and onDestroy() method:

Using with AndroidX

If you've migrated to AndroidX, you will need to add the following dependencies in build.gradle of the app.

Make sure both of the following Android Gradle plugin flags are set to true in your gradle.properties file:

Using with the Android Support Library

If your app is still using the Android Support Library, you will need to add the following dependencies in build.gradle of the app.

Add the Library using React Native

Add Files — Add .AAR & build.gradle

1. In your React Native project, go to the android folder, then open the settings.gradle file. (Figure 11)

2. Add the include code to your settings.gradle file:

Save & close.

3. Go back to open the android folder in your React Native project. (Figure 12)

4. Next, create a new folder and name it netperf-lib. (Figure 13)

5. Copy the provided .AAR file to the new netperf-lib folder. (Figure 14)

6. Next, copy the build.gradle file to the same folder. (Figure 15)

Add Dependencies

1. Go back to the android folder in your React Native project. (Figure 16)

2. Next, open the app folder. (Figure 17)

3. Open the build.gradle file. (Figure 18)

4. In build.gradle, find the dependencies code. Add the following line:

Example dependencies code results in build.gradle:

Add Services

Open your app's AndroidManifest.xml file, then add these services and receivers REQUIRED by our library.

Initialize the Library in React Native

1. Open the MainApplication LAUNCHER file in your React Native project. Add the following import :

Example import code results in MainApplication:

2. In the public class section of your MainApplication, create the following global variable.

3. Next, in the onCreate() method of your MainApplication, add the library declaration. (Figure 19)

4. Finally, in the onDestroy() method of your MainApplication, unregister the library. (Figure 19b)

Example code results in MainApplication:

Add the Library Using Xcode with Swift — Adding .framework Package

1. Open your existing project in Xcode. Right-click the project folder to create a New Group folder under your main project. (Figure 1) In this example, we’ve renamed the folder to Frameworks. (Figure 2)

2. Next, drag and drop the provided framework file Netperf-lib-xxx.framework into your newly created Frameworks folder. (Figure 3)

3. A pop-up will appear with these default options selected: Copy items if needed Create folder references (Target project should be selected) Once verified, click Finish. (Figure 4)

4. Now, select and highlight your project from the left-hand side. — Make sure your target is selected in the center window (under Targets) and the main window is on the General tab. (Figure 5)

5. Take the Netperf-lib-xxx.framework framework from the left-hand window and drag and drop this into the Embedded Binaries section. (Figure 6)

6. Before proceeding, verify that the provided framework also appears under the Linked Frameworks and Libraries section. Set the status to Required if it is not already. (Figure 7)

7. Now you’re ready to edit the ViewController. Select ViewController.swift from the left-hand menu to edit the ViewController class. (Figure 8)

8. Then, add the following code to use the framework with location: (Figure 9)

9. If you wish to use the framework without location, add the following code instead: (Figure 10)

10. Finally, add the following properties to your Info.plist file.** (Figure 11)

Add the Library Using Xcode with Objective-C — Adding .framework Package

1. Open your existing project in Xcode. Right-click the project folder to create a New Group folder under your main project. (Figure 1) In this example, we’ve renamed the folder to Frameworks. (Figure 2)

2. Next, drag and drop the provided framework file Netperf.framework into your newly created Frameworks folder. (Figure 3)

3. A pop-up will appear with these default options selected: Copy items if needed Create folder references (Target project should be selected) Once verified, click Finish. (Figure 4)

4. Now, select and highlight your project from the left-hand side. — Make sure your target is selected in the center window (under Targets) and the main window is on the General tab. (Figure 5)

5. Take the Netperf-lib-xxx.framework framework from the left-hand window and drag and drop this into the Embedded Binaries section. (Figure 6)

6. Before proceeding, verify that the provided framework also appears under the Linked Frameworks and Libraries section. Set the status to Required if it is not already. (Figure 7)

7. Now you’re ready to Create a new Swift File. In the Xcode menu click File —> New —> File. This should display the following windows: (Figure 8, Figure 9, Figure 10)

8. After creating your Swift file, find and highlight the file in the left-hand menu, which will allow you to edit the contents. To use the framework with location, add the following code to File_Name.swift. (Figure 11)

9. If you wish to use the framework without location, add the following code instead: (Figure 12)

10. Then, edit the new Bridging Header file. Add the following code to the new File_Name.Bridging-Header.h file that now appears in the left-hand menu. (Figure 13)

11. Next, use the library in your AppDelegate.m file. Add the following code: (Figure 14)

12. Finally, add the following properties to your Info.plist file. ** (Figure 15)

Using the Library for Fine-Grained and Energy-Efficient Geolocation

Upgrading the Library

Upgrade the Library using Android Studio

1. Open Android Studio to your existing project. Then, right-click the project folder and select Open Module Settings. (Figure 20)

2. In Module Settings window, select + in top corner to add the updated dependency module. (Figure 21)

3. Select Import .JAR/.AAR package, click Next. (Figure 22)

4. Browse for the new .AAR file and hit Finish. (Figure 23)

5. You should now see a list of all your dependencies. Select the old module dependency, and remove it by clicking on the — button. (Figure 24)

6. Now add the new module dependency by clicking on the + button and selecting the latest release file. Then hit OK. (Figure 25 & 26)

7. Hit OK again to close out of the module settings window. Repeat these steps each time when upgrading to the latest release.

1. Open your existing project in Xcode. Right-click the project folder to create a New Group folder under your main project. (Figure 1)
In this example, we’ve renamed the folder to Frameworks. (Figure 2)

3. A pop-up will appear with these default options selected:

Copy items if needed

Create folder references

(Target project should be selected)

Once verified, click Finish. (Figure 4)

1. Open your existing project in Xcode. Right-click the project folder to create a New Group folder under your main project. (Figure 1)
In this example, we’ve renamed the folder to Frameworks. (Figure 2)

3. A pop-up will appear with these default options selected:

Copy items if needed

Create folder references

(Target project should be selected)

Once verified, click Finish. (Figure 4)