{"__v":13,"_id":"55f1a1e6229b772300779a34","category":{"__v":7,"_id":"55f1970339e3e8190068b2b8","pages":["55f1a1e6229b772300779a34","55f1b11b39e3e8190068b2f1","55f1b59b39e3e8190068b2fc","55f1b6215fe76419007dc760","55f1b69539e3e8190068b2fe","55f1b90a5fe76419007dc763","55f1b93ffd98c42300acc643"],"project":"55de06fa57f7b20d0097636b","version":"55de06fa57f7b20d0097636e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-10T14:43:15.288Z","from_sync":false,"order":2,"slug":"android-sdk","title":"Android SDK"},"parentDoc":null,"project":"55de06fa57f7b20d0097636b","user":"55de06e19db51a0d0064947d","version":{"__v":10,"_id":"55de06fa57f7b20d0097636e","project":"55de06fa57f7b20d0097636b","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"],"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: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:3.0.3'\\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](http://docs.pushspring.com/docs/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 Google Play Services to retrieve the device's Android Advertising Id.  This identifier is used for retargeting and reengagement campaigns that you'll run later.  You **MUST** integrate Google Play Services into your application and implement an interface called **PSGooglePlayConnector** that allows the PushSpring SDK to communicate with Google Play Services.  The sample application included with the SDK has an implementation of this interface that you may use in your own application.\n\nFor 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>YOUR_API_KEY</em> with the API key you got from the PushSpring dashboard:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PushSpring pushSpring = PushSpring.sharedPushSpring();\\npushSpring.onCreate(this, PS_API_KEY, googlePlayConnector);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n**googlePlayConnector** is an instance of your implementation of **PSGooglePlayConnector**.  There is a sample implementation to start from in PushSpringSample/src/com/pushspring/sample/GooglePlayConnector.java.\n\n**NOTE**: If your Main Activity has a launchMode of singleTop, you'll need to make sure to save off new intents used to activate it when its onNewIntent() method is called, and then call into the PushSpring SDK again to display a received PushSpring notification:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"@Override\\nprotected void onNewIntent(Intent intent) {\\nsuper.onNewIntent(intent);\\nsetIntent(intent);\\n//now getIntent() should always return the last received intent\\npushSpring.onCreate(this, PS_API_KEY, googlePlayConnector);\\n}\\n\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\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\": \"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(this);\",\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(this);\",\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: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:3.0.3'\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](http://docs.pushspring.com/docs/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 Google Play Services to retrieve the device's Android Advertising Id. This identifier is used for retargeting and reengagement campaigns that you'll run later. You **MUST** integrate Google Play Services into your application and implement an interface called **PSGooglePlayConnector** that allows the PushSpring SDK to communicate with Google Play Services. The sample application included with the SDK has an implementation of this interface that you may use 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>YOUR_API_KEY</em> with the API key you got from the PushSpring dashboard: [block:code] { "codes": [ { "code": "PushSpring pushSpring = PushSpring.sharedPushSpring();\npushSpring.onCreate(this, PS_API_KEY, googlePlayConnector);", "language": "java" } ] } [/block] **googlePlayConnector** is an instance of your implementation of **PSGooglePlayConnector**. There is a sample implementation to start from in PushSpringSample/src/com/pushspring/sample/GooglePlayConnector.java. **NOTE**: If your Main Activity has a launchMode of singleTop, you'll need to make sure to save off new intents used to activate it when its onNewIntent() method is called, and then call into the PushSpring SDK again to display a received PushSpring notification: [block:code] { "codes": [ { "code": "@Override\nprotected void onNewIntent(Intent intent) {\nsuper.onNewIntent(intent);\nsetIntent(intent);\n//now getIntent() should always return the last received intent\npushSpring.onCreate(this, PS_API_KEY, googlePlayConnector);\n}\n", "language": "java" } ] } [/block] [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": "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(this);", "language": "java" } ] } [/block] Add the following line to your **onStop()** override: [block:code] { "codes": [ { "code": "PushSpring.sharedPushSpring().onSessionEnd(this);", "language": "java" } ] } [/block]