Publish v4.0.1 (#8)

placed · Aug 30, 2017 · 2b2be1b · 2b2be1b
1 parent 2214d34
commit 2b2be1b
Show file tree

Hide file tree

Showing 14 changed files with 153 additions and 128 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,18 @@
-# Placed Affiliate SDK (Android) v1.30
-
-## Integrating your application with the Placed Monetization SDK
-
-### Adding the dependency to your project
+# Placed Affiliate SDK
+
+## 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 SDK has been designed for easy setup and integration with both new and existing mobile applications.
+
+## Setup
+
+Integrating the Placed SDK into your app involves a few steps as described below.
+
+### First, add the dependency to your project
+
+Before you can integrate the Placed SDK into your app, you need to add the relevant dependency to your app.
 
 1. Add the following to your **root** `build.gradle` file:
 
@@ -20,9 +30,11 @@
 
     ```
     dependencies {
-        ...
+        // other dependencies go here...
 
-        compile 'com.placed.client:android-persistent-sdk:1.30'
+        // Use the latest patch version of the Placed SDK
+        // noinspection AndroidLintGradleDynamicVersion
+        compile 'com.placed.client:android-persistent-sdk:4.0.+'
     }
     ```
 
@@ -47,115 +59,55 @@
         }
     }
     ```
-  
-### Configuration
-* Add the application key provided to you by Placed in the application tag of your **AndroidManifest.xml**.
-        <meta-data android:name="placed_app_key" android:value="YOUR_APP_KEY" />  
 
-* Request runtime location permission (Android 6.0 Marshmallow)
+At this point your app should build, although the Placed SDK will not start yet.
 
-    If your app targets Android 6.0 Marshmallow (API level 23) or higher, your app will need prompt for `ACCESS_FINE_LOCATION` permission at runtime. You can read more information in Android's documentation for [Requesting Permissions at Run Time](http://developer.android.com/training/permissions/requesting.html).
+### Second, integrate the Placed SDK
 
-    You'll want to add this permission prompt to the Activity that calls `PlacedAgent.registerApp()` or `PlacedAgent.registerAppWithDialog`. For example:
+Once you've added the Placed SDK as an app dependency, adding the Placed SDK to your app involves several 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.
 
-        //-------
-        // Add a constant for the request code
-        private static final int REQUEST_CODE_PERMISSION = <unique int for requesting location permission for the use of the sdk>;
+#### AndroidManifest.xml changes
 
-        //--------
-        // This if() block needs to happen before PlacedAgent.registerApp() or PlacedAgent.registerAppWithDialog() is called
-        if(ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
-            ActivityCompat.requestPermissions(this, new String[] {Manifest.permission.ACCESS_FINE_LOCATION}, REQUEST_CODE_PERMISSION);
-            return;
-        }
+Add the application key provided to you by Placed in the application tag of your **AndroidManifest.xml**.
 
-        //---------
-        // This code needs to go into the onRequestPermissionsResult() method in the same Activity that calls ActivityCompat.requestPermissions
-        if(requestCode == REQUEST_CODE_PERMISSION) {
-            for(int idx = 0; idx < permissions.length; ++idx) {
-                if(permissions[idx].equals(Manifest.permission.ACCESS_FINE_LOCATION) && grantResults[idx] == PackageManager.PERMISSION_GRANTED) {
-                    // call a method that register the app or call one of the PlacedAgent registerApp methods
-                    break;
-                }
-            }
-        }
+```
+<meta-data android:name="placed_app_key" android:value="YOUR_APP_KEY" />
+```
+
+#### Prompting for location permission
+
+If you don't already prompt for fine location permission, you should do so before registering the user with the Placed SDK.
+
+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).
+
+Notice in this case the fine location permission is requested before registering the user and acceptance triggers app registion as described below.
+
+### Registering a user
+
+Once you've prompted for fine location permission you need to register your user with the Placed SDK.
+
+The following code snippet registers the user:
+
+```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).
+
+## 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]).
+
+## Support
+For further guidance contact [[email protected]](mailto:[email protected]).
+
+## Reference
+
+`static void registerUser(final Context context)`
 
-### Integration
-
-* Place the following code in your application's main activity `onCreate` method:
-* Make sure to replace **YOUR\_APP\_KEY** with your application key
-
-        /**
-        * Call this method for default opt-in behavior, this will show a dialog
-        * to your users asking them to opt-in to location tracking (recommended)
-        * This dialog will only be shown once over the lifetime of the application
-        */
-        PlacedAgent.registerAppWithDialog(YourMainActivity.this, YOUR_APP_KEY);  
-        
-        /**
-        * If you want a custom theme for the dialog, pass in the style/theme as a parameter
-        */
-        PlacedAgent.registerAppWithDialog(YourMainActivity.this, YOUR_APP_KEY, R.style.your_dialog_theme);
-
-* To send additional information, such as demographics, to Placed, please include the following code in your application's main activity after calling `PlacedAgent.registerAppWithDialog`:
-
-* Log a unique identifier
-
-        /**  
-        * This method logs a unique id  
-        *  
-        * @param context Your application's context  
-        * @param id the unique id  
-        */
-        PlacedAgent.logUniqueId(Context context, String id)
-
-* Sending demographic data
-
-        /**
-        * This method is used to log demographics
-        *
-        * @param jsonString A string representing a JSON blob of the raw data returned  
-        * by the source API
-        * @param source A string with the name of the demographics source (e.g. Facebook)  
-        * @param version If the source API is versioned please include the version number.  
-        */
-        PlacedAgent.logDemographics(Context context, String jsonString, String source, String version)
-
-### Register
-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])
-
-## Restricting Device Id Collection
-To limit device id collection to just the advertising id, add the following line of code before calling registerApp or registerAppWithDialog
-        PlacedAgent.setRestrictDeviceIds(YourMainActivity.this, true)
-
-### That's it!
-
-### Support
-For further guidance contact [[email protected]](mailto:[email protected])
-
-## SDK Glossary
-
-### Placed Agent Methods  
-  
-`static void registerAppWithDialog(final Activity activity, final String appKey)`  
-`static void registerAppWithDialog(final Activity activity, final String appKey, Integer theme)`  
-Show the user an opt-in dialog for Placed location measurement. If the user accepts the terms in the dialog, they will be opted-in to Placed location measurement. Pass in the optional theme parameter to use a custom dialog theme.
-
-`static boolean shouldDisplayDialog(final Activity activity, final String appKey)`  
-Returns true if the current device can have an opt-in dialog displayed, meaning that they are either in the US or US only has been disabled and they have not seen a dialog before. To be used when implementing a custom opt-in dialog.
-
-`static void registerApp(Context context, String appKey)`  
-Register this install of your app with Placed. This method automatically opts a user in to location measurement. Usually you would use this method if you are creating your own opt-in dialog, or want finer control of when a user is opted-in.  
-  
-`static void logUniqueId(Context context, String id)`  
-Log an `id` that is unique to this install of your application. This method is used with custom integrations with Placed.
-  
-`static void setRestrictDeviceIds(Context context, boolean restrict)`
-If you app falls under Google's policy rules that prohibit collection of various device identifiers, call this method with `restrict` set to true so that Placed will only collect identifiers that meet that policy.
-  
-`static void logFacebookLikes(Context context, String jsonString)`  
-This method is used for custom integrations with Placed. If you have questions please inquire with your contact at Placed.  
-  
-`static void logDemographics(Context context, String jsonString, String source, String version)`  
-This method is used for custom integrations with Placed. If you have questions please inquire with your contact at Placed.  
+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.
diff --git a/SampleApp/app/build.gradle b/SampleApp/app/build.gradle
@@ -2,7 +2,7 @@ apply plugin: 'com.android.application'
 
 android {
     compileSdkVersion 25
-    buildToolsVersion "25.0.2"
+    buildToolsVersion "25.0.3"
 
     defaultConfig {
         applicationId "com.placed.android.sampleapp"
@@ -25,9 +25,9 @@ android {
 dependencies {
     compile fileTree(dir: 'libs', include: ['*.jar'])
     testCompile 'junit:junit:4.12'
-    compile 'com.android.support:appcompat-v7:25.0.1'
+    compile 'com.android.support:appcompat-v7:25.3.1'
 
-    // Use the latest version of the Placed SDK
+    // Use the latest patch version of the Placed SDK
     // noinspection AndroidLintGradleDynamicVersion
-    compile 'com.placed.client:android-persistent-sdk:1.+'
+    compile 'com.placed.client:android-persistent-sdk:4.0.1'
 }
diff --git a/SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java b/SampleApp/app/src/main/java/com/placed/android/sampleapp/MainActivity.java
@@ -1,12 +1,15 @@
 package com.placed.android.sampleapp;
 
 import android.Manifest;
+import android.content.DialogInterface;
 import android.content.pm.PackageManager;
+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.os.Bundle;
 import android.util.Log;
 
 import com.placed.client.android.persistent.PlacedAgent;
@@ -16,6 +19,8 @@ public class MainActivity extends AppCompatActivity {
 
     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);
@@ -26,7 +31,7 @@ protected void onCreate(Bundle savedInstanceState) {
             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.");
-            registerApp();
+            registerUser();
         }
     }
 
@@ -38,8 +43,8 @@ public void onRequestPermissionsResult(int requestCode, @NonNull String[] permis
             for (int idx = 0; idx < permissions.length; idx++) {
                 if (permissions[idx].equals(Manifest.permission.ACCESS_FINE_LOCATION)) {
                     if (grantResults[idx] == PackageManager.PERMISSION_GRANTED) {
-                        Log.d(TAG, "User granded ACCESS_FINE_LOCATION permission. Proceeding to register app with Placed.");
-                        registerApp();
+                        Log.d(TAG, "User granted ACCESS_FINE_LOCATION permission. Proceeding to register app with Placed.");
+                        registerUser();
                     } else {
                         Log.d(TAG, "User denied granting ACCESS_FINE_LOCATION permission. Can't proceed to register app with Placed.");
                     }
@@ -49,7 +54,25 @@ public void onRequestPermissionsResult(int requestCode, @NonNull String[] permis
         }
     }
 
-    private void registerApp() {
-        PlacedAgent.registerAppWithDialog(this, getString(R.string.placed_api_key));
+    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();
+
+            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();
+        }
     }
 }
diff --git a/SampleApp/build.gradle b/SampleApp/build.gradle
@@ -5,7 +5,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:2.2.2'
+        classpath 'com.android.tools.build:gradle:2.3.3'
 
         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files

diff --git a/SampleApp/gradle/wrapper/gradle-wrapper.properties b/SampleApp/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
-#Fri Aug 26 12:57:19 PDT 2016
+#Thu Aug 10 13:02:15 PDT 2017
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-2.14.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-3.3-all.zip
diff --git a/repository/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.aar b/repository/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.aar
diff --git a/...itory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.aar.md5 b/...itory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.aar.md5
@@ -0,0 +1 @@
+dc01379a7b739b763b6a286a60f54d1e
diff --git a/...tory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.aar.sha1 b/...tory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.aar.sha1
@@ -0,0 +1 @@
+9bb2da8e56d39851d438f0b8ea573995e6855074
diff --git a/repository/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.pom b/repository/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.pom
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.placed.client</groupId>
+  <artifactId>android-persistent-sdk</artifactId>
+  <version>4.0.1</version>
+  <packaging>aar</packaging>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.android.gms</groupId>
+      <artifactId>play-services-ads</artifactId>
+      <version>10.0.1</version>
+    </dependency>
+    <dependency>
+      <groupId>com.google.android.gms</groupId>
+      <artifactId>play-services-location</artifactId>
+      <version>10.0.1</version>
+    </dependency>
+    <dependency>
+      <groupId>edu.emory.mathcs</groupId>
+      <artifactId>JTransforms</artifactId>
+      <version>2.4</version>
+    </dependency>
+    <dependency>
+      <groupId>com.jakewharton</groupId>
+      <artifactId>disklrucache</artifactId>
+      <version>1.2.1</version>
+    </dependency>
+    <dependency>
+      <groupId>com.squareup.retrofit2</groupId>
+      <artifactId>retrofit</artifactId>
+      <version>2.0.1</version>
+    </dependency>
+    <dependency>
+      <groupId>com.squareup.retrofit2</groupId>
+      <artifactId>converter-gson</artifactId>
+      <version>2.0.1</version>
+    </dependency>
+    <dependency>
+      <groupId>com.squareup.okhttp3</groupId>
+      <artifactId>logging-interceptor</artifactId>
+      <version>3.2.0</version>
+    </dependency>
+  </dependencies>
+</project>
diff --git a/...itory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.pom.md5 b/...itory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.pom.md5
@@ -0,0 +1 @@
+331352195591f0a0e1061592ce1339ca
diff --git a/...tory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.pom.sha1 b/...tory/com/placed/client/android-persistent-sdk/4.0.1/android-persistent-sdk-4.0.1.pom.sha1
@@ -0,0 +1 @@
+590174a621c1bbf6727f5149a4747d9124b8054a
diff --git a/repository/com/placed/client/android-persistent-sdk/maven-metadata.xml b/repository/com/placed/client/android-persistent-sdk/maven-metadata.xml
@@ -3,12 +3,13 @@
   <groupId>com.placed.client</groupId>
   <artifactId>android-persistent-sdk</artifactId>
   <versioning>
-    <release>1.30</release>
+    <release>4.0.1</release>
     <versions>
       <version>1.20</version>
       <version>1.21</version>
       <version>1.30</version>
+      <version>4.0.1</version>
     </versions>
-    <lastUpdated>20170607000353</lastUpdated>
+    <lastUpdated>20170810230819</lastUpdated>
   </versioning>
 </metadata>
diff --git a/repository/com/placed/client/android-persistent-sdk/maven-metadata.xml.md5 b/repository/com/placed/client/android-persistent-sdk/maven-metadata.xml.md5
@@ -1 +1 @@
-0155210dd1db1f4ceea54d927f897c24
+baa08aa89120b27b34666499d5f9da67
diff --git a/repository/com/placed/client/android-persistent-sdk/maven-metadata.xml.sha1 b/repository/com/placed/client/android-persistent-sdk/maven-metadata.xml.sha1
@@ -1 +1 @@
-82512170e2a1663169a12540d7145ead63db4e5c
+3714f23c4e88a1cd47ecaa1b7a99c348b1bf9397
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		0155210dd1db1f4ceea54d927f897c24
		baa08aa89120b27b34666499d5f9da67
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		82512170e2a1663169a12540d7145ead63db4e5c
		3714f23c4e88a1cd47ecaa1b7a99c348b1bf9397