Release v4.1.0 (#12)

README.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-The Placed SDK for Android is designed to help you add Placed location gathering to your app. It exposes simple public API calls that can be used to turn location gathering on.
+The Placed SDK for Android is designed to help you add Placed location gathering to your app. It exposes simple public API calls that can be used to turn on and off location gathering.
 
 The SDK has been designed for easy setup and integration with both new and existing mobile applications.
 
@@ -16,10 +16,10 @@ Before you can integrate the Placed SDK into your app, you need to add the relev
 
 1. Add the following to your **root** `build.gradle` file:
 
-    ```
+    ```gradle
     allprojects {
         repositories {
-            ...
+            // other repositories
 
             maven { url "https://raw.githubusercontent.com/placed/android-placed-sdk/master/repository" }
         }
@@ -28,15 +28,15 @@ Before you can integrate the Placed SDK into your app, you need to add the relev
 
 2. Add the following to your **app** `build.gradle` file:
 
-    ```
+    ```gradle
     dependencies {
         // other dependencies go here...
 
         // Use the latest patch version of the Placed SDK
         // noinspection AndroidLintGradleDynamicVersion
         compile 'com.placed.client:android-persistent-sdk:4.0.+'
 
-        // NOTE: If you use any Google Play services APIs above version 
+        // NOTE: If you use any Google Play services APIs above version
         // 10.0.1, add the following to avoid crashes caused by inconsistent
         // API versions.
         compile('com.google.android.gms:play-services-ads:<your-version>') {
@@ -51,7 +51,7 @@ Before you can integrate the Placed SDK into your app, you need to add the relev
 3. You may encounter Lint error: 'InvalidPackage: Package not included in Android' related to Okio and Retrofit. (This is a known issue with Okio that you can read about [here](https://github.com/square/okio/issues/58).)
 
     If so, create a `lint.xml` with the following contents:
-    ```
+    ```xml
     <lint>
         <issue id="InvalidPackage">
             <ignore regexp=".*okio.*" />
@@ -61,9 +61,10 @@ Before you can integrate the Placed SDK into your app, you need to add the relev
     ```
 
     And reference it from your **app** `build.gradle` file:
-    ```
+    ```gradle
     android {
-        ...
+        // ...
+        
         lintOptions {
             lintConfig file("lint.xml")
         }
@@ -74,50 +75,53 @@ At this point your app should build, although the Placed SDK will not start yet.
 
 ### Second, integrate the Placed SDK
 
-Once you've added the Placed SDK as an app dependency, adding the Placed SDK to your app involves several more steps:
+Once you've added the Placed SDK as an app dependency, completing installation of the Placed SDK to your app involves a couple more steps:
 
-1. Add the Placed provided app key to AndroidManifest.xml
-2. Prompt for location permission
-3. Register the user for location collection by the Placed SDK.
+1. Prompt for location permission.
+2. Register the user with Placed SDK.
 
-#### AndroidManifest.xml changes
+#### Location Permission
 
-Add the application key provided to you by Placed in the application tag of your **AndroidManifest.xml**.
+As outlined in Section 5 of the [Placed Affiliate Agreement](https://affiliate.placed.com/placed-affiliate-agreement/), you must satisfy two requirements prior to registering a user with the Placed SDK:  
+1. *Gather Express Consent for User Data Collection via Opt-in Dialog*  
+In addition having a legally compliant privacy policy describing Placed’s collection of location and device information, you must include a discrete opt-in dialog which gathers express consent for data collection. This dialog appears prior to the fine location permission prompt, and includes:
+    - The language: “*Aggregated device data, including location and apps, is measured for the purposes of market research by Placed, Inc.*”
+    - Links to the Placed [Terms of Service](https://www.placed.com/terms-of-service) and [Privacy Policy](https://www.placed.com/privacy-policy)
+    - Buttons to “Accept” or “Cancel”
 
-```
-<meta-data android:name="placed_app_key" android:value="YOUR_APP_KEY" />
-```
+2. *Prompt for Fine Location Permission*  
+Eligible users must allow fine location permission, which subsequently triggers app registration as described in the [Register a User](#register-a-user) section.
 
-#### Prompting for location permission
+For an example of the opt-in dialog and location permission prompt, please refer to the [main activity of the sample app](./SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java). We have also provided a [gallery for inspiration](./gallery) on how you can better integrate the opt-in experience into your app.
 
-If you don't already prompt for fine location permission, you should do so before registering the user with the Placed SDK.
+#### Register a user
 
-For an example, see the [main activity in the sample app](https://github.com/placed/android-placed-sdk/blob/master/SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java).
+Once you've prompted for location permission and gathered express consent to collect user data, you need to register your user with the Placed SDK. There are __two options__ when registering a user with the Placed SDK.
 
-Notice in this case the fine location permission is requested before registering the user and acceptance triggers app registion as described below.
+##### Option 1: Add your Placed app key to your AndroidManifest.xml
 
-### Registering a user
-
-Once you've prompted for fine location permission you need to register your user with the Placed SDK.
+```xml
+<meta-data android:name="placed_app_key" android:value="YOUR_APP_KEY" />
+```
 
-The following code snippet registers the user:
+And then call:
 
 ```java
 PlacedAgent.registerUser(this);
 ```
 
-For an example, see the [main activity in the sample app](https://github.com/placed/android-placed-sdk/blob/master/SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java).
+For an example, see the [main activity in the sample app](./SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java).
 
-## How to join
-Please contact your Placed representative to find out how to register your account. If you do not have a representative yet, please email [[email protected]](mailto:[email protected]).
+##### Option 2: Add your Placed app key at runtime
 
-## Support
-For further guidance contact [[email protected]](mailto:[email protected]).
+All you have to do is call:
 
-## Reference
+```java
+PlacedAgent.registerUser(this, "YOUR_APP_KEY");
+```
 
-`static void registerUser(final Context context)`
+## How to join
+Please contact your Placed representative to find out how to register your account. If you do not have a representative yet, please email [[email protected]](mailto:[email protected]).
 
-This is the main method to register the user with the Placed SDK and begin
-location collection by the Placed SDK. If you have EULA or terms of service that the user is required to accept before tracking,
-call this method after the user accepts those terms.
+## Support
+For further guidance, please contact [[email protected]](mailto:[email protected]).

SampleApp/app/build.gradle

@@ -2,11 +2,10 @@ apply plugin: 'com.android.application'
 
 android {
     compileSdkVersion 25
-    buildToolsVersion "25.0.3"
 
     defaultConfig {
         applicationId "com.placed.android.sampleapp"
-        minSdkVersion 9
+        minSdkVersion 14
         targetSdkVersion 25
         versionCode 1
         versionName "1.0"
@@ -23,11 +22,11 @@ android {
 }
 
 dependencies {
-    compile fileTree(dir: 'libs', include: ['*.jar'])
-    testCompile 'junit:junit:4.12'
-    compile 'com.android.support:appcompat-v7:25.3.1'
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    testImplementation 'junit:junit:4.12'
+    implementation 'com.android.support:appcompat-v7:25.4.0'
 
     // Use the latest patch version of the Placed SDK
     // noinspection AndroidLintGradleDynamicVersion
-    compile 'com.placed.client:android-persistent-sdk:4.0.+'
+    implementation 'com.placed.client:android-persistent-sdk:4.1.+'
 }

SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java

@@ -1,34 +1,32 @@
 package com.placed.android.sampleapp;
 
 import android.Manifest;
-import android.content.DialogInterface;
+import android.content.Intent;
 import android.content.pm.PackageManager;
+import android.net.Uri;
 import android.os.Bundle;
-import android.preference.PreferenceManager;
 import android.support.annotation.NonNull;
 import android.support.v4.app.ActivityCompat;
 import android.support.v4.content.ContextCompat;
-import android.support.v7.app.AlertDialog;
 import android.support.v7.app.AppCompatActivity;
 import android.util.Log;
+import android.widget.Toast;
 
 import com.placed.client.android.persistent.PlacedAgent;
 
-public class MainActivity extends AppCompatActivity {
+public class MainActivity extends AppCompatActivity implements SampleDialog.SampleDialogListener {
     private static final String TAG = MainActivity.class.getSimpleName();
 
     private static final int REQUEST_CODE_PERMISSION = 1;
 
-    private static final String PREF_KEY_PLACED_DIALOG_SHOWN = "placed_dialog_shown";
-
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_main);
 
         if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
             Log.d(TAG, "Requesting for ACCESS_FINE_LOCATION permission.");
-            ActivityCompat.requestPermissions(this, new String[] { Manifest.permission.ACCESS_FINE_LOCATION }, REQUEST_CODE_PERMISSION);
+            ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, REQUEST_CODE_PERMISSION);
         } else {
             Log.d(TAG, "Already have ACCESS_FINE_LOCATION permission. Proceeding to register app with Placed.");
             registerUser();
@@ -55,24 +53,38 @@ public void onRequestPermissionsResult(int requestCode, @NonNull String[] permis
     }
 
     private void registerUser() {
-        if (!PreferenceManager.getDefaultSharedPreferences(this).getBoolean(PREF_KEY_PLACED_DIALOG_SHOWN, false)) {
-            PreferenceManager.getDefaultSharedPreferences(this)
-                    .edit()
-                    .putBoolean(PREF_KEY_PLACED_DIALOG_SHOWN, true)
-                    .apply();
+        if (!PlacedAgent.isUserRegistered(this)) {
+            SampleDialog sampleDialog = new SampleDialog(this);
+            sampleDialog.show();
+            sampleDialog.onActionListener = this;
+        } else {
+            Toast.makeText(this, "User already registered!", Toast.LENGTH_SHORT).show();
+        }
+    }
+
+    @Override
+    public void onActionReceived(SampleDialogAction action) {
+        switch (action) {
+            case TERMS:
+                Intent termsIntent = new Intent(Intent.ACTION_VIEW, Uri.parse("https://www.placed.com/terms-of-service"));
+                startActivity(termsIntent);
+                break;
+
+            case PRIVACY:
+                Intent privacyIntent = new Intent(Intent.ACTION_VIEW, Uri.parse("https://www.placed.com/privacy-policy"));
+                startActivity(privacyIntent);
+                break;
+
+            case ACCEPT:
+                PlacedAgent.registerUser(this);
+                break;
+
+            case CANCEL:
+                PlacedAgent.deregisterUser(this);
+                break;
 
-            new AlertDialog.Builder(this)
-                    .setTitle("Asking your users for consent")
-                    .setMessage("Implement your own user experience to ask your users to collect Placed data.")
-                    .setPositiveButton("OK", new DialogInterface.OnClickListener() {
-                        @Override
-                        public void onClick(DialogInterface dialogInterface, int i) {
-                            PlacedAgent.registerUser(MainActivity.this);
-                        }
-                    })
-                    .setNegativeButton("Cancel", null)
-                    .create()
-                    .show();
+            default:
+                break;
         }
     }
 }

SampleApp/app/src/main/java/com/placed/android/sampleapp/SampleDialog.java

@@ -0,0 +1,65 @@
+package com.placed.android.sampleapp;
+
+import android.app.Dialog;
+import android.content.Context;
+import android.os.Bundle;
+import android.support.annotation.NonNull;
+import android.view.View;
+import android.view.Window;
+
+enum SampleDialogAction {
+    TERMS, PRIVACY, ACCEPT, CANCEL
+}
+
+public class SampleDialog extends Dialog {
+    public interface SampleDialogListener {
+        void onActionReceived(SampleDialogAction action);
+    }
+
+    public SampleDialogListener onActionListener;
+
+    SampleDialog(@NonNull Context context) {
+        super(context);
+    }
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        requestWindowFeature(Window.FEATURE_NO_TITLE);
+        setContentView(R.layout.sample_dialog);
+
+        setupButtons();
+    }
+
+    private void setupButtons() {
+        findViewById(R.id.btn_terms).setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(View v) {
+                onActionListener.onActionReceived(SampleDialogAction.TERMS);
+            }
+        });
+
+        findViewById(R.id.btn_privacy).setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(View v) {
+                onActionListener.onActionReceived(SampleDialogAction.PRIVACY);
+            }
+        });
+
+        findViewById(R.id.btn_accept).setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(View v) {
+                onActionListener.onActionReceived(SampleDialogAction.ACCEPT);
+                dismiss();
+            }
+        });
+
+        findViewById(R.id.btn_cancel).setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(View v) {
+                onActionListener.onActionReceived(SampleDialogAction.CANCEL);
+                dismiss();
+            }
+        });
+    }
+}

SampleApp/app/src/main/res/drawable-hdpi/rounded_corners_shape.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<shape
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:shape="rectangle" >
+
+    <solid
+        android:color="@color/sample_orange" >
+    </solid>
+
+    <corners
+        android:radius="5dp" >
+    </corners>
+
+</shape>

SampleApp/app/src/main/res/layout/activity_main.xml

@@ -12,5 +12,5 @@
     <TextView
         android:layout_width="wrap_content"
         android:layout_height="wrap_content"
-        android:text="Hello from Placed!" />
+        android:text="@string/hello_from_placed" />
 </RelativeLayout>