Merge pull request #365 from Microsoft/distribute

Merge distribute to develop

Author: guperrot

README.md

@@ -16,17 +16,20 @@ The SDK is currently in private beta release and we support the following servic
 
 2. **Crashes**: The Mobile Center SDK will automatically generate a crash log every time your app crashes. The log is first written to the device's storage and when the user starts the app again, the crash report will be forwarded to Mobile Center. Collecting crashes works for both beta and live apps, i.e. those submitted to Google Play or other app stores. Crash logs contain viable information for you to help resolve the issue. The SDK gives you a lot of flexibility how to handle a crash log. As a developer you can collect and add additional information to the report if you like.
 
+3. **Distribute**: Our SDK will let your users install a new version of the app when you distribute it via Mobile Center. With a new version of the app available, the SDK will present an update dialog to the users to either download or ignore the latest version. Once they click "Download", SDK will start the installation process of your application. Note that this feature will `NOT` work if your app is deployed to the app store, if you are developing locally or if the app is a debug build.
+
 This document contains the following sections:
 
 1. [Prerequisites](#1-prerequisites)
 2. [Add Mobile Center SDK modules](#2-add-mobile-center-sdk-modules)
 3. [Start the SDK](#3-start-the-sdk)
 4. [Analytics APIs](#4-analytics-apis)
 5. [Crashes APIs](#5-crashes-apis)
-6. [Advanced APIs](#6-advanced-apis)
-7. [Troubleshooting](#7-troubleshooting)
-8. [Contributing](#8-contributing)
-9. [Contact](#9-contact)
+6. [Distribute APIs](#6-distribute-apis)
+7. [Advanced APIs](#7-advanced-apis)
+8. [Troubleshooting](#8-troubleshooting)
+9. [Contributing](#9-contributing)
+10. [Contact](#10-contact)
 
 Let's get started with setting up Mobile Center Android SDK in your app to use these services:
 
@@ -43,15 +46,17 @@ The Mobile Center SDK is designed with a modular approach – a developer only n
 
 Below are the steps on how to integrate our compiled libraries in your application using Android Studio and Gradle.
 
-1. Open your app level build.gradle file (app/build.gradle) and include the dependencies that you want in your project. Each SDK module needs to be added as a separate dependency in this section. If you would want to use both Analytics and Crashes, add the following lines:
+1. Open your app level build.gradle file (app/build.gradle) and include the dependencies that you want in your project. Each SDK module needs to be added as a separate dependency in this section. If you want to include all the services - Analytics, Crashes and Distribute, add the following lines:
 
     ```groovy
     dependencies {
         def mobileCenterSdkVersion = '0.5.0'
         compile "com.microsoft.azure.mobile:mobile-center-analytics:${mobileCenterSdkVersion}"
         compile "com.microsoft.azure.mobile:mobile-center-crashes:${mobileCenterSdkVersion}"
+        compile "com.microsoft.azure.mobile:mobile-center-distribute:${mobileCenterSdkVersion}"
     }
     ```
+You can remove the dependency line for the service that you don't want to include in your app.
 
 2. Save your build.gradle file and make sure to trigger a Gradle sync in Android Studio.
 
@@ -61,21 +66,27 @@ Now that you've integrated the SDK in your application, it's time to start the S
 
 To start the Mobile Center SDK in your app, follow these steps:
 
-1. **Start the SDK:**  Mobile Center provides developers with two services to get started – Analytics and Crashes. In order to use these services, you need to opt in for the service(s) that you'd like, meaning by default no services are started and you will have to explicitly call each of them when starting the SDK. Insert the following line inside your app's main activity class' `onCreate` callback.
+1. **Start the SDK:**  Mobile Center provides developers with these services to get started – Analytics, Crashes and Distribute. In order to use these services, you need to opt in for the service(s) that you'd like, meaning by default no services are started and you will have to explicitly call each of them when starting the SDK. Insert the following line inside your app's main activity class' `onCreate` callback.
 
     ```Java
-    MobileCenter.start(getApplication(), "{Your App Secret}", Analytics.class, Crashes.class);
+    MobileCenter.start(getApplication(), "{Your App Secret}", Analytics.class, Crashes.class, Distribute.class);
     ```
     You can also copy paste the `start` method call from the Overview page on Mobile Center portal once your app is selected. It already includes the App Secret so that all the data collected by the SDK corresponds to your application. Make sure to replace {Your App Secret} text with the actual value for your application.
     
-    The example above shows how to use the `start()` method and include both the Analytics and Crashes services. If you wish not to use Analytics, remove the parameter from the method call above. Note that, unless you explicitly specify each service as parameters in the start method, you can't use that Mobile Center service. Also, the `start()` API can be used only once in the lifecycle of your app – all other calls will log a warning to the console and only the services included in the first call will be available.
+    The example above shows how to use the `start()` method and include Analytics, Crashes and Distribute services. If you wish not to onboard to any of these services, say you dont want to use features provided by Distribute service, remove the parameter from the method call above. Note that, unless you explicitly specify each service as parameters in the start method, you can't use that Mobile Center service. Also, the `start()` API can be used only once in the lifecycle of your app – all other calls will log a warning to the console and only the services included in the first call will be available.
+
+    For example - if you just want to onboard to Analytics service, you should modify the start() API call like below:
+    ```Java
+    MobileCenter.start(getApplication(), "{Your App Secret}", Analytics.class);
+    ```
 
     Android Studio will automatically suggest the required import statements once you insert the `start()` method-call, but if you see an error that the class names are not recognized, add the following lines to the import statements in your activity class:
     
     ```Java
     import com.microsoft.azure.mobile.MobileCenter;
     import com.microsoft.azure.mobile.analytics.Analytics;
     import com.microsoft.azure.mobile.crashes.Crashes;
+    import com.microsoft.azure.mobile.distribute.Distribute;
     ```
 
 ## 4. Analytics APIs
@@ -217,7 +228,26 @@ You create your own Crashes listener and assign it like this:
         }
         ```
 
-## 6. Advanced APIs
+## 6. Distribute APIs
+
+You can easily let your users get the latest version of your app by integrating `Distribute` service of Mobile Center SDK. All you need to do is pass the service name as a parameter in the `start()` API call. Once the activity is created, the SDK checks for new updates in the background. If it finds a new update, users will see a dialog with three options - `Download`,`Postpone` and `Ignore`. If the user presses `Download`, it will trigger the new version to be installed. Postpone will delay the download until the app is opened again. Ignore will not prompt the user again for that particular app version.
+
+You can easily provide your own resource strings if you'd like to localize the text displayed in the update dialog. Look at the string files [here](https://github.com/Microsoft/mobile-center-sdk-android/blob/distribute/sdk/mobile-center-distribute/src/main/res/values/strings.xml). Use the same string name and specify the localized value to be reflected in the dialog in your own app resource files.  
+
+* **Enable or disable Distribute:**  You can change the enabled state by calling the `Distribute.setEnabled()` method. If you disable it, the SDK will not prompt your users when a new version is available for install. To re-enable it, pass `true` as a parameter in the same method.
+
+    ```Java
+    Distribute.setEnabled(false);
+    ```
+
+    You can also check if the service is enabled or not using the `isEnabled()` method. Note that it will only disable SDK features for Distribute service which is in-app updates for your application and has nothing to do with disabling `Distribute` service from Mobile Center.
+
+    ```Java
+    Distribute.isEnabled();
+    ```
+        
+
+## 7. Advanced APIs
 
 * **Debugging**: You can control the amount of log messages that show up from the Mobile Center SDK in LogCat. Use the `MobileCenter.setLogLevel()` API to enable additional logging while debugging. The log levels correspond to the ones defined in `android.util.Log`. By default, it is set it to `ASSERT` for non-debuggable applications and `WARN` for debuggable applications.
 
@@ -237,7 +267,7 @@ You create your own Crashes listener and assign it like this:
         MobileCenter.setEnabled(false);
     ```
 
-## 7. Troubleshooting
+## 8. Troubleshooting
 
 * **How long to wait for Analytics data to appear on the portal?**
 
@@ -258,22 +288,24 @@ You create your own Crashes listener and assign it like this:
 
 * **What Android permissions are required for the SDK?**
     Depending on the services you use, the following permissions are required:
-    - Analytics, Crashes: `INTERNET`, `ACCESS_NETWORK_STATE`
+    - All services: `INTERNET`, `ACCESS_NETWORK_STATE`
+    - Distribute: `REQUEST_INSTALL_PACKAGES`, `DOWNLOAD_WITHOUT_NOTIFICATION`
 
     Required permissions are automatically merged into your app's manifest by the SDK.
     
-    
-## 8. Contributing
+    None of these permissions require user approval at runtime, those are all install time permissions.
+
+## 9. Contributing
 
 We're looking forward to your contributions via pull requests.
 
-### 8.1 Code of Conduct
+### 9.1 Code of Conduct
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact opencode@microsoft.com with any additional questions or comments.
 
-### 8.2 Contributor License
+### 9.2 Contributor License
 
 You must sign a [Contributor License Agreement](https://cla.microsoft.com/) before submitting your pull request. To complete the Contributor License Agreement (CLA), you will need to submit a request via the [form](https://cla.microsoft.com/) and then electronically sign the CLA when you receive the email containing the link to the document. You need to sign the CLA only once to cover submission to any Microsoft OSS project. 
 
-## 9. Contact
+## 10. Contact
 If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to open a Github issue here or contact us at mobilecentersdk@microsoft.com.

apps/sasquatch/build.gradle

@@ -21,11 +21,19 @@ android {
     }
 }
 
+repositories {
+    maven {
+        url "http://dl.bintray.com/mobile-center/mobile-center-snapshot"
+    }
+}
+
 dependencies {
-    def version = "0.5.0"
+    def version = "0.6.0-4"
     compile "com.android.support:appcompat-v7:${rootProject.ext.supportLibVersion}"
     projectDependencyCompile project(':sdk:mobile-center-analytics')
     projectDependencyCompile project(':sdk:mobile-center-crashes')
+    projectDependencyCompile project(':sdk:mobile-center-distribute')
     jcenterDependencyCompile "com.microsoft.azure.mobile:mobile-center-analytics:${version}"
     jcenterDependencyCompile "com.microsoft.azure.mobile:mobile-center-crashes:${version}"
+    jcenterDependencyCompile "com.microsoft.azure.mobile:mobile-center-distribute:${version}"
 }

apps/sasquatch/src/main/AndroidManifest.xml

@@ -4,6 +4,7 @@
           package="com.microsoft.azure.mobile.sasquatch">
 
     <application
+        android:name=".SasquatchApplication"
         android:allowBackup="true"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"

apps/sasquatch/src/main/java/com/microsoft/azure/mobile/sasquatch/SasquatchApplication.java

@@ -0,0 +1,15 @@
+package com.microsoft.azure.mobile.sasquatch;
+
+import android.app.Application;
+import android.util.Log;
+
+import com.microsoft.azure.mobile.MobileCenter;
+
+public class SasquatchApplication extends Application {
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        MobileCenter.setLogLevel(Log.VERBOSE);
+    }
+}

apps/sasquatch/src/main/java/com/microsoft/azure/mobile/sasquatch/activities/MainActivity.java

@@ -9,6 +9,7 @@
 import android.support.annotation.Nullable;
 import android.support.v7.app.AlertDialog;
 import android.support.v7.app.AppCompatActivity;
+import android.text.TextUtils;
 import android.util.Log;
 import android.view.Menu;
 import android.view.MenuItem;
@@ -22,16 +23,13 @@
 import com.microsoft.azure.mobile.crashes.AbstractCrashesListener;
 import com.microsoft.azure.mobile.crashes.Crashes;
 import com.microsoft.azure.mobile.crashes.model.ErrorReport;
+import com.microsoft.azure.mobile.distribute.Distribute;
 import com.microsoft.azure.mobile.sasquatch.R;
 import com.microsoft.azure.mobile.sasquatch.features.TestFeatures;
 import com.microsoft.azure.mobile.sasquatch.features.TestFeaturesListAdapter;
 
-import java.lang.reflect.Method;
-
-
 public class MainActivity extends AppCompatActivity {
 
-    static final String APP_SECRET = "45d1d9f6-2492-4e68-bd44-7190351eb5f3";
     static final String APP_SECRET_KEY = "appSecret";
     static final String LOG_URL_KEY = "logUrl";
     private static final String LOG_TAG = "MobileCenterSasquatch";
@@ -46,26 +44,28 @@ protected void onCreate(Bundle savedInstanceState) {
         StrictMode.setThreadPolicy(new StrictMode.ThreadPolicy.Builder().detectDiskReads().detectDiskWrites().build());
 
         /* Set custom log URL if one was configured in settings. */
-        String logUrl = sSharedPreferences.getString(LOG_URL_KEY, null);
-        if (logUrl != null) {
-            try {
-
-                /* Method name changed and jCenter not yet updated so need to use reflection. */
-                Method setLogUrl;
-                try {
-                    setLogUrl = MobileCenter.class.getMethod("setLogUrl", String.class);
-                } catch (NoSuchMethodException e) {
-                    setLogUrl = MobileCenter.class.getMethod("setServerUrl", String.class);
-                }
-                setLogUrl.invoke(null, logUrl);
-            } catch (Exception e) {
-                throw new RuntimeException(e);
-            }
+        String logUrl = sSharedPreferences.getString(LOG_URL_KEY, getString(R.string.log_url));
+        if (!TextUtils.isEmpty(logUrl)) {
+            MobileCenter.setLogUrl(logUrl);
         }
-        MobileCenter.setLogLevel(Log.VERBOSE);
+
+        /* Set crash listener. */
         Crashes.setListener(getCrashesListener());
-        MobileCenter.start(getApplication(), getAppSecret(), Analytics.class, Crashes.class);
 
+        /* Set distribute urls. */
+        String installUrl = getString(R.string.install_url);
+        if (!TextUtils.isEmpty(installUrl)) {
+            Distribute.setInstallUrl(installUrl);
+        }
+        String apiUrl = getString(R.string.api_url);
+        if (!TextUtils.isEmpty(apiUrl)) {
+            Distribute.setApiUrl(apiUrl);
+        }
+
+        /* Start Mobile center. */
+        MobileCenter.start(getApplication(), sSharedPreferences.getString(APP_SECRET_KEY, getString(R.string.app_secret)), Analytics.class, Crashes.class, Distribute.class);
+
+        /* Print last crash. */
         Log.i(LOG_TAG, "Crashes.hasCrashedInLastSession=" + Crashes.hasCrashedInLastSession());
         Crashes.getLastSessionCrashReport(new ResultCallback<ErrorReport>() {
 
@@ -77,6 +77,7 @@ public void onResult(@Nullable ErrorReport data) {
             }
         });
 
+        /* Populate UI. */
         ((TextView) findViewById(R.id.package_name)).setText(String.format(getString(R.string.sdk_source_format), getPackageName().substring(getPackageName().lastIndexOf(".") + 1)));
         TestFeatures.initialize(this);
         ListView listView = (ListView) findViewById(R.id.list);
@@ -100,18 +101,6 @@ public boolean onOptionsItemSelected(MenuItem item) {
         return true;
     }
 
-    private String getAppSecret() {
-        String appSecret = sSharedPreferences.getString(APP_SECRET_KEY, null);
-        if (appSecret == null) {
-            SharedPreferences.Editor editor = sSharedPreferences.edit();
-            editor.putString(APP_SECRET_KEY, APP_SECRET);
-            editor.apply();
-            appSecret = sSharedPreferences.getString(APP_SECRET_KEY, null);
-        }
-        Toast.makeText(this, String.format(getString(R.string.app_secret_toast), appSecret), Toast.LENGTH_SHORT).show();
-        return appSecret;
-    }
-
     private AbstractCrashesListener getCrashesListener() {
         return new AbstractCrashesListener() {
             @Override