{"_id":"55f1a1e6229b772300779a34","parentDoc":null,"category":{"_id":"55f1970339e3e8190068b2b8","pages":["55f1a1e6229b772300779a34","55f1b11b39e3e8190068b2f1","55f1b59b39e3e8190068b2fc","55f1b6215fe76419007dc760","55f1b69539e3e8190068b2fe","55f1b90a5fe76419007dc763","55f1b93ffd98c42300acc643"],"project":"55de06fa57f7b20d0097636b","version":"55de06fa57f7b20d0097636e","__v":7,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-10T14:43:15.288Z","from_sync":false,"order":2,"slug":"android-sdk","title":"Android SDK"},"project":"55de06fa57f7b20d0097636b","__v":13,"user":"55de06e19db51a0d0064947d","version":{"_id":"55de06fa57f7b20d0097636e","project":"55de06fa57f7b20d0097636b","__v":14,"createdAt":"2015-08-26T18:35:38.642Z","releaseDate":"2015-08-26T18:35:38.642Z","categories":["55de06fb57f7b20d0097636f","55f1962e3936d52d00fb3c8f","55f1970339e3e8190068b2b8","55f1970d229b772300779a1f","55f1971cfd98c42300acc605","55f1d5c7fd98c42300acc69f","563cbfe4260dde0d00c5e9d4","5644cf437f1fff210078e690","57dc1bbd3ed3450e00dc9ea7","58a600a2243dd30f00fd8773","58ed1bdc068f780f00f64602","58f13b3a4f0ee50f00e24e81","58f173f792f9020f009cad16","591b42f8e633fd0f00077c5a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-10T15:29:42.819Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Integrating the PushSpring SDK into your app is straightforward, with a basic integration taking around 15 minutes.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Adhering to Google policies\",\n  \"body\": \"Don't forget to get your users' consent before transmitting data to PushSpring. For more on that see: [Getting User Consent Before Profiling](http://developer.pushspring.com/v1.0/docs/getting-user-consent-before-profiling)\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Using Gradle dependencies\"\n}\n[/block]\nYou must be using Gradle version 2.4 or above. You can check and change the version number in the 'distributionUrl' property in your app's gradle wrapper properties file, 'gradle/wrapper/gradle-wrapper.properties', e.g. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"distributionUrl=https\\\\://services.gradle.org/distributions/gradle-2.4-all.zip\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nRun './gradlew build' and it will download the new version automatically and rebuild your app.\n\nAdd the PushSpring repository to a repositories section in your app's build.gradle, e.g.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"repositories {\\n  jcenter()\\n  maven {\\n    url \\\"http://public.pushspring.com.s3.amazonaws.com/SDK/Android\\\"\\n  }\\n}\",\n      \"language\": \"groovy\"\n    }\n  ]\n}\n[/block]\nYou should also upgrade your Gradle plugin version to 1.2.0, or above, in your top level build.gradle file e.g.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"buildscript {\\n    repositories {\\n        jcenter()\\n    }\\n    dependencies {\\n        classpath 'com.android.tools.build:gradle:1.2.0'\\n    }\\n}\",\n      \"language\": \"groovy\"\n    }\n  ]\n}\n[/block]\nNow add the SDK to the dependencies section in your app's build.gradle, e.g. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"dependencies {\\n    compile 'com.pushspring.sdk:PushSpringSDK:4.0.9'\\n}\",\n      \"language\": \"groovy\"\n    }\n  ]\n}\n[/block]\nRebuilding on the command line or in Android Studio will download the new versions of Gradle, the Gradle plugin, and the PushSpring SDK. Skip to [Step 3](doc:getting-started-2#3-google-play-services) to complete the integration.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Manually add the SDK\"\n}\n[/block]\nIf you aren't using Gradle dependencies and wish to integrate the SDK manually then follow the instructions below.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2a. Request SDK Binary\"\n}\n[/block]\nEmail <support:::at:::pushspring.com> for the binary and samples.\n\nInside the SDK, you'll find a folder called **PushSpringSDK**. You'll also find a complete sample app in a folder called **PushSpringSDKSample** inside the PushSpringSamples ZIP archive.</p>\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"API LEVELS\",\n  \"body\": \"The published SDK is designed to work with a minimum api level of 10 (Android 2.3 “Gingerbread”).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2b. Adding the SDK to your Android Studio Project\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note\",\n  \"body\": \"If you are using Eclipse/ADT instead of Android Studio skip ahead to Step 2a.\"\n}\n[/block]\n\nOpen your app's project in Android Studio.  Click the File menu and select Import Module..., enter the path to the PushSpringSDK folder, and click Finish.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/JnWAuuBQouWRhL9hNZd6_asimport.png\",\n        \"asimport.png\",\n        \"2502\",\n        \"1630\",\n        \"#7dac4c\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nRight-click on your app module and select Open Module Settings.  In the dialog that pops up, select **Dependencies**, click the **+** button on the bottom of the dialog, and select **Module Dependency**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/TPDKRC4IQz6ApnShRLef_asmodulesettings.png\",\n        \"asmodulesettings.png\",\n        \"2644\",\n        \"1714\",\n        \"#164784\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect **:PushSpringSDK** in the **Choose Modules** dialog, click **OK** and click **OK** again in the **Project Structure** dialog.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/FeD4v3CSEmAek851hslc_asmoduledependency.png\",\n        \"asmoduledependency.png\",\n        \"2644\",\n        \"1714\",\n        \"#185296\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2c. Adding the SDK to your Eclipse/ADT Project\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note\",\n  \"body\": \"If you are not using Eclipse/ADT skip this section.\"\n}\n[/block]\nOpen your app's project in Eclipse. Click the File menu and select Import..., expand \"General\", and choose \"Existing projects into Workspace\" (Note the screenshots below are for ADT v22).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/s7sd85eRWeJTRqDmCM2g_import.png\",\n        \"import.png\",\n        \"1273\",\n        \"858\",\n        \"#3c5a8d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nIn the Import dialog enter the path to the PushSpringSDK folder for the root directory. Make sure the PushSpringSDK project is chosen. Choose to copy projects into the workspace and click Finish.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/G1yzT54Smu8C7iGnJvAg_importproject.png\",\n        \"importproject.png\",\n        \"1274\",\n        \"857\",\n        \"#924b27\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nRight-click on your project and click Properties. In the dialog that pops up select the Android category and then click the Add button.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4WaUQhlxRyJ7hlWt8ADA_properties.png\",\n        \"properties.png\",\n        \"1274\",\n        \"857\",\n        \"#354866\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect PushSpringSDK and click OK in the project selection dialog and ok again in the project properties dialog.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/IunKjlrGTsm28lVowVOK_projectselection.png\",\n        \"projectselection.png\",\n        \"1275\",\n        \"858\",\n        \"#365178\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Google Play Services\"\n}\n[/block]\nThe PushSpring SDK relies on devices' Android Advertising IDs to perform the retargeting and re-engagement campaigns that you'll run later.  In order to obtain these IDs, you **MUST** integrate Google Play Services into your application.  The PushSpring sample applications all contain example code for retrieving Android Advertising IDs in your own application. For information on integrating the Google Play Services into your application, see the [Android Developer Documentation](https://developer.android.com/google/play-services/).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"4. Configuring your API Key\"\n}\n[/block]\nBefore getting started, get your app's API key from the PushSpring dashboard.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8HLYZIUSSoW8bEJwfwlt_Screen%20Shot%202015-12-01%20at%208.33.25%20PM.png\",\n        \"Screen Shot 2015-12-01 at 8.33.25 PM.png\",\n        \"2550\",\n        \"1162\",\n        \"#60463a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"5. AndroidManifest.xml Changes\"\n}\n[/block]\nThe PushSpringSDK requires that you specify the INTERNET permission if your app does not already do so.  This allows your app to communicate with PushSpring's servers.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<uses-permission android:name=\\\"android.permission.INTERNET\\\" />\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"6. Main Activity Changes\"\n}\n[/block]\nAdd an import statement to the top of the file to import the PushSpring SDK.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import com.pushspring.sdk.PushSpring;\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nAdd the following line to your main activity (the activity with category LAUNCHER), in its onCreate() override, replacing <em>PS_API_KEY</em> with the API key you got from the PushSpring dashboard and <em>ANDROID_ADVERTISING_ID</em> and <IS_LIMIT_AD_TRACKING_ENABLED></em> with the values obtained from AdvertisingIdClient:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PushSpring pushSpring = PushSpring.sharedPushSpring();\\npushSpring.init(this, PS_API_KEY, ANDROID_ADVERTISING_ID, IS_LIMIT_AD_TRACKING_ENABLED);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nIf you are not yet retrieving the Android Advertising ID for other purposes, the following code sample shows how to do so, and then pass the id to PushSpring's init() method.  There is also a sample which demonstrates how to retrieve the advertising ID and ad tracking flag from the AdvertisingIdClient in PushSpringSDKSample/src/com/pushspring/sample/MainActivity.java.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"final PushSpring pushSpring = PushSpring.sharedPushSpring();\\nfinal Context context = this;\\n\\n// cannot call for Advertising ID on main thread\\nnew Thread(new Runnable() {\\n\\t@Override\\n  public void run() {\\n  \\ttry {\\n    \\tfinal AdvertisingIdClient.Info adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context);\\n      pushSpring.init(context, PS_API_KEY, adInfo.getId(), adInfo.isLimitAdTrackingEnabled());\\n    } catch (IOException | GooglePlayServicesNotAvailableException | GooglePlayServicesRepairableException e) {\\n    \\tLog.e(\\\"TestUsageCollection\\\", \\\"Unable to get the advertising info for this context\\\", e);\\n    }\\n  }\\n}).start();\\n\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"7. Support for API Level < 14\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note\",\n  \"body\": \"Skip this step if your app uses an API Level >= 14\"\n}\n[/block]\nThe SDK automatically wires up the ActivityStarted and ActivityStopped events for API level >= 14. If your app will run on devices with API levels below 14, you will need to also add two more lines to your main activity. Add the following line to your **onStart()** override:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PushSpring.sharedPushSpring().onSessionStart();\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nAdd the following line to your **onStop()** override:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PushSpring.sharedPushSpring().onSessionEnd();\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]","excerpt":"Initial integration with Android SDK","slug":"getting-started-2","type":"basic","title":"Getting Started"}

Getting Started

Initial integration with Android SDK

Integrating the PushSpring SDK into your app is straightforward, with a basic integration taking around 15 minutes. [block:callout] { "type": "warning", "title": "Adhering to Google policies", "body": "Don't forget to get your users' consent before transmitting data to PushSpring. For more on that see: [Getting User Consent Before Profiling](http://developer.pushspring.com/v1.0/docs/getting-user-consent-before-profiling)" } [/block] [block:api-header] { "type": "basic", "title": "1. Using Gradle dependencies" } [/block] You must be using Gradle version 2.4 or above. You can check and change the version number in the 'distributionUrl' property in your app's gradle wrapper properties file, 'gradle/wrapper/gradle-wrapper.properties', e.g. [block:code] { "codes": [ { "code": "distributionUrl=https\\://services.gradle.org/distributions/gradle-2.4-all.zip", "language": "text" } ] } [/block] Run './gradlew build' and it will download the new version automatically and rebuild your app. Add the PushSpring repository to a repositories section in your app's build.gradle, e.g. [block:code] { "codes": [ { "code": "repositories {\n jcenter()\n maven {\n url \"http://public.pushspring.com.s3.amazonaws.com/SDK/Android\"\n }\n}", "language": "groovy" } ] } [/block] You should also upgrade your Gradle plugin version to 1.2.0, or above, in your top level build.gradle file e.g. [block:code] { "codes": [ { "code": "buildscript {\n repositories {\n jcenter()\n }\n dependencies {\n classpath 'com.android.tools.build:gradle:1.2.0'\n }\n}", "language": "groovy" } ] } [/block] Now add the SDK to the dependencies section in your app's build.gradle, e.g. [block:code] { "codes": [ { "code": "dependencies {\n compile 'com.pushspring.sdk:PushSpringSDK:4.0.9'\n}", "language": "groovy" } ] } [/block] Rebuilding on the command line or in Android Studio will download the new versions of Gradle, the Gradle plugin, and the PushSpring SDK. Skip to [Step 3](doc:getting-started-2#3-google-play-services) to complete the integration. [block:api-header] { "type": "basic", "title": "2. Manually add the SDK" } [/block] If you aren't using Gradle dependencies and wish to integrate the SDK manually then follow the instructions below. [block:api-header] { "type": "basic", "title": "2a. Request SDK Binary" } [/block] Email <support@pushspring.com> for the binary and samples. Inside the SDK, you'll find a folder called **PushSpringSDK**. You'll also find a complete sample app in a folder called **PushSpringSDKSample** inside the PushSpringSamples ZIP archive.</p> [block:callout] { "type": "info", "title": "API LEVELS", "body": "The published SDK is designed to work with a minimum api level of 10 (Android 2.3 “Gingerbread”)." } [/block] [block:api-header] { "type": "basic", "title": "2b. Adding the SDK to your Android Studio Project" } [/block] [block:callout] { "type": "warning", "title": "Note", "body": "If you are using Eclipse/ADT instead of Android Studio skip ahead to Step 2a." } [/block] Open your app's project in Android Studio. Click the File menu and select Import Module..., enter the path to the PushSpringSDK folder, and click Finish. [block:image] { "images": [ { "image": [ "https://files.readme.io/JnWAuuBQouWRhL9hNZd6_asimport.png", "asimport.png", "2502", "1630", "#7dac4c", "" ] } ] } [/block] Right-click on your app module and select Open Module Settings. In the dialog that pops up, select **Dependencies**, click the **+** button on the bottom of the dialog, and select **Module Dependency**. [block:image] { "images": [ { "image": [ "https://files.readme.io/TPDKRC4IQz6ApnShRLef_asmodulesettings.png", "asmodulesettings.png", "2644", "1714", "#164784", "" ] } ] } [/block] Select **:PushSpringSDK** in the **Choose Modules** dialog, click **OK** and click **OK** again in the **Project Structure** dialog. [block:image] { "images": [ { "image": [ "https://files.readme.io/FeD4v3CSEmAek851hslc_asmoduledependency.png", "asmoduledependency.png", "2644", "1714", "#185296", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "2c. Adding the SDK to your Eclipse/ADT Project" } [/block] [block:callout] { "type": "warning", "title": "Note", "body": "If you are not using Eclipse/ADT skip this section." } [/block] Open your app's project in Eclipse. Click the File menu and select Import..., expand "General", and choose "Existing projects into Workspace" (Note the screenshots below are for ADT v22). [block:image] { "images": [ { "image": [ "https://files.readme.io/s7sd85eRWeJTRqDmCM2g_import.png", "import.png", "1273", "858", "#3c5a8d", "" ] } ] } [/block] In the Import dialog enter the path to the PushSpringSDK folder for the root directory. Make sure the PushSpringSDK project is chosen. Choose to copy projects into the workspace and click Finish. [block:image] { "images": [ { "image": [ "https://files.readme.io/G1yzT54Smu8C7iGnJvAg_importproject.png", "importproject.png", "1274", "857", "#924b27", "" ] } ] } [/block] Right-click on your project and click Properties. In the dialog that pops up select the Android category and then click the Add button. [block:image] { "images": [ { "image": [ "https://files.readme.io/4WaUQhlxRyJ7hlWt8ADA_properties.png", "properties.png", "1274", "857", "#354866", "" ] } ] } [/block] Select PushSpringSDK and click OK in the project selection dialog and ok again in the project properties dialog. [block:image] { "images": [ { "image": [ "https://files.readme.io/IunKjlrGTsm28lVowVOK_projectselection.png", "projectselection.png", "1275", "858", "#365178", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "3. Google Play Services" } [/block] The PushSpring SDK relies on devices' Android Advertising IDs to perform the retargeting and re-engagement campaigns that you'll run later. In order to obtain these IDs, you **MUST** integrate Google Play Services into your application. The PushSpring sample applications all contain example code for retrieving Android Advertising IDs in your own application. For information on integrating the Google Play Services into your application, see the [Android Developer Documentation](https://developer.android.com/google/play-services/). [block:api-header] { "type": "basic", "title": "4. Configuring your API Key" } [/block] Before getting started, get your app's API key from the PushSpring dashboard. [block:image] { "images": [ { "image": [ "https://files.readme.io/8HLYZIUSSoW8bEJwfwlt_Screen%20Shot%202015-12-01%20at%208.33.25%20PM.png", "Screen Shot 2015-12-01 at 8.33.25 PM.png", "2550", "1162", "#60463a", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "5. AndroidManifest.xml Changes" } [/block] The PushSpringSDK requires that you specify the INTERNET permission if your app does not already do so. This allows your app to communicate with PushSpring's servers. [block:code] { "codes": [ { "code": "<uses-permission android:name=\"android.permission.INTERNET\" />", "language": "xml" } ] } [/block] [block:api-header] { "type": "basic", "title": "6. Main Activity Changes" } [/block] Add an import statement to the top of the file to import the PushSpring SDK. [block:code] { "codes": [ { "code": "import com.pushspring.sdk.PushSpring;", "language": "java" } ] } [/block] Add the following line to your main activity (the activity with category LAUNCHER), in its onCreate() override, replacing <em>PS_API_KEY</em> with the API key you got from the PushSpring dashboard and <em>ANDROID_ADVERTISING_ID</em> and <IS_LIMIT_AD_TRACKING_ENABLED></em> with the values obtained from AdvertisingIdClient: [block:code] { "codes": [ { "code": "PushSpring pushSpring = PushSpring.sharedPushSpring();\npushSpring.init(this, PS_API_KEY, ANDROID_ADVERTISING_ID, IS_LIMIT_AD_TRACKING_ENABLED);", "language": "java" } ] } [/block] If you are not yet retrieving the Android Advertising ID for other purposes, the following code sample shows how to do so, and then pass the id to PushSpring's init() method. There is also a sample which demonstrates how to retrieve the advertising ID and ad tracking flag from the AdvertisingIdClient in PushSpringSDKSample/src/com/pushspring/sample/MainActivity.java. [block:code] { "codes": [ { "code": "final PushSpring pushSpring = PushSpring.sharedPushSpring();\nfinal Context context = this;\n\n// cannot call for Advertising ID on main thread\nnew Thread(new Runnable() {\n\t@Override\n public void run() {\n \ttry {\n \tfinal AdvertisingIdClient.Info adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context);\n pushSpring.init(context, PS_API_KEY, adInfo.getId(), adInfo.isLimitAdTrackingEnabled());\n } catch (IOException | GooglePlayServicesNotAvailableException | GooglePlayServicesRepairableException e) {\n \tLog.e(\"TestUsageCollection\", \"Unable to get the advertising info for this context\", e);\n }\n }\n}).start();\n", "language": "java" } ] } [/block] [block:api-header] { "type": "basic", "title": "7. Support for API Level < 14" } [/block] [block:callout] { "type": "warning", "title": "Note", "body": "Skip this step if your app uses an API Level >= 14" } [/block] The SDK automatically wires up the ActivityStarted and ActivityStopped events for API level >= 14. If your app will run on devices with API levels below 14, you will need to also add two more lines to your main activity. Add the following line to your **onStart()** override: [block:code] { "codes": [ { "code": "PushSpring.sharedPushSpring().onSessionStart();", "language": "java" } ] } [/block] Add the following line to your **onStop()** override: [block:code] { "codes": [ { "code": "PushSpring.sharedPushSpring().onSessionEnd();", "language": "java" } ] } [/block]