{"__v":25,"_id":"55ecd6c554a67b1700edcf40","category":{"__v":35,"_id":"55e67b5556007d23005fee7d","pages":["55e67b91de6fef23009480cb","55e67c28de6fef23009480ce","55e67c3cde6fef23009480d1","55e680e185a9741900314e96","55e682b7de6fef23009480dc","55ecd69bb2714d2100f227c0","55ecd6c554a67b1700edcf40","55ecd6edae66a30d00446ce7","55ecd777b2714d2100f227c2","55ecda5a7659d21700a7ef9b","55ecdaf6ae66a30d00446cf3","55ed006a0d968e2100de831e","55ed0258c9d5b3350072ae7a","55ee66a073d3941700f760e5","55f5ef61a1dea80d00a5dec5","55f5f38618b39b0d00c27eb0","55f9f86417b9d00d00969e29","55f9fdc8aba81f0d00a1156d","561b10b4c89cc30d0082154f","561b110a03bce90d00c4bd11","561c6195ad272c0d00a892dd","561c6ca0be5fb20d00077754","564f3e66c133343500286ca0","565b955b922c9a0d00d1f124","566784d2919aaa0d008e32db","566e1ee5972a290d00552084","569c58d77c3e44170014114f","56a2692f6928550d006c8327","56ca6c868014e417002bfe54","56cfa5386c5d7a13005eec0f","56e73d86555c030e00a52a73","56e7460c9000b120000ffe2e","56e8c19e99c6400e003820cf","56e8c53fc88bf80e00f8bed8","56f06ff4d386ce0e008e9b21"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-02T04:30:13.305Z","from_sync":false,"order":1,"slug":"install-in-your-app","title":"Install in your app"},"parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d2bd8e2463351700f67dd7","version":{"__v":9,"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c"],"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-07T00:13:57.274Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The following steps assume you have access to the Carnival Platform, the latest version of either Android Studio or Eclipse with ADT installed, and are targeting at least Android _API level 14_ (Ice Cream Sandwich-4.0) – The Carnival SDK will not work on earlier versions of Android.\",\n  \"title\": \"Note\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Version 3.x Migration\",\n  \"body\": \"If you are migrating to v3.x from v2.x, [click here for migration docs](v3-migration).\\nOld 2.x integration steps can be found [here](android-integration-2x).\"\n}\n[/block]\n# Android Studio\n\nEdit the `build.gradle` file for your application (Module: app) and add the following repositories and dependencies:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"repositories {\\n\\tmaven {\\n\\t\\turl \\\"https://github.com/carnivalmobile/maven-repository/raw/master/\\\"\\n  }\\n}\\n\\ndependencies {\\n  // Append this line to the dependencies section\\n\\tcompile 'com.carnival.sdk:carnival:3.+'\\n}\",\n      \"language\": \"groovy\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Multidex\",\n  \"body\": \"When integrating any 3rd party library with Android, you may run into issues of exceeding 65,000 methods. It's best to enable Multidex to support this limitation. Read more [here](http://developer.android.com/tools/building/multidex.html)\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"Using `3.+` for the version part of the dependencies will aways get the latest minor version of the Carnival 3.x SDK. This will keep you up to date with minor upgrades to the SDK. Alternatively, you can specify this explicitly to stay on a certain version.\"\n}\n[/block]\n#### Manifest Permissions\n\nWe now need to set the permissions and services inside your application's \"AndroidManifest.xml\". Below is a snippet for you to use. If your code already has some of the following permissions, they do not need to be put in twice. These permissions go in between the `<manifest> </manifest>` tags.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<uses-permission android:name=\\\"android.permission.INTERNET\\\" />\\n<uses-permission android:name=\\\"android.permission.WAKE_LOCK\\\" />\\n<uses-permission android:name=\\\"com.google.android.c2dm.permission.RECEIVE\\\" />\\n\\n<uses-permission android:name=\\\"${applicationId}.permission.C2D_MESSAGE\\\" />\\n\\n<permission\\n\\tandroid:name=\\\"${applicationId}.permission.C2D_MESSAGE\\\"\\n\\tandroid:protectionLevel=\\\"signature\\\" />\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nThe following should be added within the manifest's `<application> </application>` tags.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<receiver\\n  android:name=\\\"com.google.android.gms.gcm.GcmReceiver\\\"\\n  android:exported=\\\"true\\\"\\n  android:permission=\\\"com.google.android.c2dm.permission.SEND\\\" >\\n  <intent-filter>\\n      <action android:name=\\\"com.google.android.c2dm.intent.RECEIVE\\\" />\\n      <category android:name=\\\"${applicationId}\\\" />\\n  </intent-filter>\\n</receiver>\\n\\n<meta-data\\n\\tandroid:name=\\\"com.google.android.gms.version\\\"\\n\\tandroid:value=\\\":::at:::integer/google_play_services_version\\\" />\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nThe Broadcast Receiver tells Android where to send GCM messages in order to generate notifications for your application. The metadata is required by Google Play Services to verify what version of its services are installed on the device.\n\n## Connecting to Carnival\nCollect your SDK Key from [Carnival](https://app.carnivalmobile.com). Navigate to **Settings** -> **Developer** to find this.\n\nThere is only one line of code that needs to go into your [Application onCreate()](http://developer.android.com/reference/android/app/Application.html#onCreate%28%29) method.\nThe Context that gets passed to Carnival should usually be `this` or `getApplicationContext()`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Remember to add your import\\nimport com.carnival.sdk.Carnival;\\n\\nCarnival.startEngine(getApplicationContext(), \\\"SDK_KEY\\\");\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nSet your application to use your Application class in the manifest if you haven't already:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<application\\n        android:name=\\\".MyApplication\\\"\\n        ... >\\n  \\t...\\n</application>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n### Notification Styling\n\nOne other optional small task you might want to do while integrating is to set the notification icon. Android notifications use a custom icon for your application that appears in the status bar. The [Android documentation](http://developer.android.com/design/style/iconography.html#notification) has a detailed explanation on how to create and style an icon for this use, but if you are using Android Studio the easiest way is to go **File** -> **New** -> **Image Asset** and select **Notification Icons** from the **Icon Type** drop-down. Change the **Name** to any value, for example `ic_stat_notification`.\n\nOnce you have your icon in your application, tell Carnival about it by creating a `NotificationConfig` object and calling `setSmallIcon` with the icon's drawable resource.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"NotificationConfig config = new NotificationConfig();\\nconfig.setSmallIcon(R.drawable.ic_stat_notification);\\n\\nCarnival.setNotificationConfig(config);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"NotificationConfig\",\n  \"body\": \"[`NotificationConfig`](http://carnivalmobile.github.io/carnival-android-sdk/javadoc/latest/reference/com/carnival/sdk/NotificationConfig.html) has many features to customize the behavior and style of push notifications. Check the [javadoc](http://carnivalmobile.github.io/carnival-android-sdk/javadoc/latest/reference/com/carnival/sdk/NotificationConfig.html) for the full list of options.\"\n}\n[/block]\n### Launch the App!\n\nFinally, launch your application on your Android device or in the emulator.\n\nLog in to [Carnival](https://app.carnivalmobile.com/), Navigate to **Settings->Developer->Device Log** and you should see your device listed.\n\n### Troubleshooting\n\nYour device should appear in the Device Log. This is located in **Settings** -> **Logs**. If you can't see your device in the Device Log, try these steps: \n\n *  Confirm when you launch your Application that there is no \"Carnival authentication failure\" warnings in the log output. If you have warnings then this means you have supplied the wrong SDK key or you have not set up the Bundle Identifier correctly. Go back through the above steps.\n * Make sure you have an active internet connection.\n * Make sure that the device has Google Play Store installed.\n * If running on the Android emulator make sure that the AVD runs the Google APIs platform based on Android 4.2.2 or higher.\n * If you get this far and still have problems, re-trace over the steps above.\n\n*You have now completed this section and your Application should be correctly registering with Carnival.*\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Next Steps\"\n}\n[/block]\n1.  [Setup Push Notifications for Android](doc:enable-push-notifications-for-android) to ensure your users can receive push notifications.\n2. [Setup in-app messages](doc:setting-up-in-app-messaging) to enable Carnivals rich In-App Messages.\n3. [Collect user data](doc:collecting-user-data) to help in segmenting and targeting your users based on their activity.","excerpt":"Integration instructions for Android Apps using Java","slug":"android-integration","type":"basic","title":"Android Integration"}

Android Integration

Integration instructions for Android Apps using Java

[block:callout] { "type": "info", "body": "The following steps assume you have access to the Carnival Platform, the latest version of either Android Studio or Eclipse with ADT installed, and are targeting at least Android _API level 14_ (Ice Cream Sandwich-4.0) – The Carnival SDK will not work on earlier versions of Android.", "title": "Note" } [/block] [block:callout] { "type": "warning", "title": "Version 3.x Migration", "body": "If you are migrating to v3.x from v2.x, [click here for migration docs](v3-migration).\nOld 2.x integration steps can be found [here](android-integration-2x)." } [/block] # Android Studio Edit the `build.gradle` file for your application (Module: app) and add the following repositories and dependencies: [block:code] { "codes": [ { "code": "repositories {\n\tmaven {\n\t\turl \"https://github.com/carnivalmobile/maven-repository/raw/master/\"\n }\n}\n\ndependencies {\n // Append this line to the dependencies section\n\tcompile 'com.carnival.sdk:carnival:3.+'\n}", "language": "groovy" } ] } [/block] [block:callout] { "type": "info", "title": "Multidex", "body": "When integrating any 3rd party library with Android, you may run into issues of exceeding 65,000 methods. It's best to enable Multidex to support this limitation. Read more [here](http://developer.android.com/tools/building/multidex.html)" } [/block] [block:callout] { "type": "info", "title": "Note", "body": "Using `3.+` for the version part of the dependencies will aways get the latest minor version of the Carnival 3.x SDK. This will keep you up to date with minor upgrades to the SDK. Alternatively, you can specify this explicitly to stay on a certain version." } [/block] #### Manifest Permissions We now need to set the permissions and services inside your application's "AndroidManifest.xml". Below is a snippet for you to use. If your code already has some of the following permissions, they do not need to be put in twice. These permissions go in between the `<manifest> </manifest>` tags. [block:code] { "codes": [ { "code": "<uses-permission android:name=\"android.permission.INTERNET\" />\n<uses-permission android:name=\"android.permission.WAKE_LOCK\" />\n<uses-permission android:name=\"com.google.android.c2dm.permission.RECEIVE\" />\n\n<uses-permission android:name=\"${applicationId}.permission.C2D_MESSAGE\" />\n\n<permission\n\tandroid:name=\"${applicationId}.permission.C2D_MESSAGE\"\n\tandroid:protectionLevel=\"signature\" />", "language": "xml" } ] } [/block] The following should be added within the manifest's `<application> </application>` tags. [block:code] { "codes": [ { "code": "<receiver\n android:name=\"com.google.android.gms.gcm.GcmReceiver\"\n android:exported=\"true\"\n android:permission=\"com.google.android.c2dm.permission.SEND\" >\n <intent-filter>\n <action android:name=\"com.google.android.c2dm.intent.RECEIVE\" />\n <category android:name=\"${applicationId}\" />\n </intent-filter>\n</receiver>\n\n<meta-data\n\tandroid:name=\"com.google.android.gms.version\"\n\tandroid:value=\"@integer/google_play_services_version\" />", "language": "xml" } ] } [/block] The Broadcast Receiver tells Android where to send GCM messages in order to generate notifications for your application. The metadata is required by Google Play Services to verify what version of its services are installed on the device. ## Connecting to Carnival Collect your SDK Key from [Carnival](https://app.carnivalmobile.com). Navigate to **Settings** -> **Developer** to find this. There is only one line of code that needs to go into your [Application onCreate()](http://developer.android.com/reference/android/app/Application.html#onCreate%28%29) method. The Context that gets passed to Carnival should usually be `this` or `getApplicationContext()`. [block:code] { "codes": [ { "code": "// Remember to add your import\nimport com.carnival.sdk.Carnival;\n\nCarnival.startEngine(getApplicationContext(), \"SDK_KEY\");", "language": "java" } ] } [/block] Set your application to use your Application class in the manifest if you haven't already: [block:code] { "codes": [ { "code": "<application\n android:name=\".MyApplication\"\n ... >\n \t...\n</application>", "language": "xml" } ] } [/block] ### Notification Styling One other optional small task you might want to do while integrating is to set the notification icon. Android notifications use a custom icon for your application that appears in the status bar. The [Android documentation](http://developer.android.com/design/style/iconography.html#notification) has a detailed explanation on how to create and style an icon for this use, but if you are using Android Studio the easiest way is to go **File** -> **New** -> **Image Asset** and select **Notification Icons** from the **Icon Type** drop-down. Change the **Name** to any value, for example `ic_stat_notification`. Once you have your icon in your application, tell Carnival about it by creating a `NotificationConfig` object and calling `setSmallIcon` with the icon's drawable resource. [block:code] { "codes": [ { "code": "NotificationConfig config = new NotificationConfig();\nconfig.setSmallIcon(R.drawable.ic_stat_notification);\n\nCarnival.setNotificationConfig(config);", "language": "java" } ] } [/block] [block:callout] { "type": "info", "title": "NotificationConfig", "body": "[`NotificationConfig`](http://carnivalmobile.github.io/carnival-android-sdk/javadoc/latest/reference/com/carnival/sdk/NotificationConfig.html) has many features to customize the behavior and style of push notifications. Check the [javadoc](http://carnivalmobile.github.io/carnival-android-sdk/javadoc/latest/reference/com/carnival/sdk/NotificationConfig.html) for the full list of options." } [/block] ### Launch the App! Finally, launch your application on your Android device or in the emulator. Log in to [Carnival](https://app.carnivalmobile.com/), Navigate to **Settings->Developer->Device Log** and you should see your device listed. ### Troubleshooting Your device should appear in the Device Log. This is located in **Settings** -> **Logs**. If you can't see your device in the Device Log, try these steps: * Confirm when you launch your Application that there is no "Carnival authentication failure" warnings in the log output. If you have warnings then this means you have supplied the wrong SDK key or you have not set up the Bundle Identifier correctly. Go back through the above steps. * Make sure you have an active internet connection. * Make sure that the device has Google Play Store installed. * If running on the Android emulator make sure that the AVD runs the Google APIs platform based on Android 4.2.2 or higher. * If you get this far and still have problems, re-trace over the steps above. *You have now completed this section and your Application should be correctly registering with Carnival.* [block:api-header] { "type": "basic", "title": "Next Steps" } [/block] 1. [Setup Push Notifications for Android](doc:enable-push-notifications-for-android) to ensure your users can receive push notifications. 2. [Setup in-app messages](doc:setting-up-in-app-messaging) to enable Carnivals rich In-App Messages. 3. [Collect user data](doc:collecting-user-data) to help in segmenting and targeting your users based on their activity.