--- title: Getting Started - Android (classic) description: Integrate the Contentsquare SDK into your Android app in minutes (installation, user consent, screen tracking, and testing) lastUpdated: 07 April 2026 source_url: html: https://docs.contentsquare.com/en/android/ md: https://docs.contentsquare.com/en/android/index.md --- > Documentation index: https://docs.contentsquare.com/llms.txt > Use this file to discover all available pages before exploring further. The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/upgrade-from-cs-sdk/). Welcome to the SDK implementation guide! This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes. ## Install the SDK Our Android SDK is shipped as an Android library (AAR) which you need to add as a dependency to your Gradle file. See [Compatibility](compatibility/) for more information. ### Include the SDK For distribution of our API we use **Maven Central Repository** which is supported by the Android build system by default. To add our SDK (or library), add the following line to your application's dependency list. * Groovy **build.gradle** ```groovy implementation "com.contentsquare.android:sdk:0.11.0" ``` * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:sdk:0.11.0") ``` The SDK autostarts when your application launches, requiring no manual initialization. If you are using an older Kotlin version, see [Compatibility](compatibility/). ### Validate SDK integration Start your application, and check logs for this output: ```text CSLIB: Contentsquare SDK 4.44.1 starting in app: com.example.testapp ``` ## Check the logs Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, or on the Contentsquare platform. To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled. ### Viewing logs in Android Studio To view SDK logs: 1. Plug your Android phone into your computer (or use an emulator) 2. Open Android Studio and start your app 3. Open the `Logcat` view and select your phone or emulator 4. Filter logs by `CSLIB` ![](https://docs.contentsquare.com/_astro/logs-android.DcmHNl7a_1VAzm1.webp) ### Enable in-app features In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration. To enable in-app features within your app, make sure your app is launched in the background. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows. If access is blocked by the Android OS, you may need to allow the restricted settings first. To do this, go to your device settings, navigate to **Apps**, tap on your app, open the **More** menu (three dots), and then tap on **Allow restricted settings**. #### On a device: scan the QR code In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone. ![Scan the QR Code (Android)](https://docs.contentsquare.com/_astro/log-visualizer-access-qr.DnZz71r7_905Is.webp) Note On Android, some devices have a built-in QR code reader feature in the default camera app. If that is not the case for you, use the [QR & Barcode Reader by TeaCapps ↗](https://play.google.com/store/apps/details?id=com.teacapps.barcodescanner\&hl=en\&gl=US). #### On an emulator: use the ADB command If you are using an emulator, use the ADB command to enable in-app features. In Contentsquare, select the Mobile icon in the menu top bar then select your application ID, and "Copy this ADB command". ![](https://docs.contentsquare.com/_astro/log-visualizer-access-adb.BaJqetXO_zt9bH.webp) The following command is copied to the clipboard: ```shell adb shell "am start -W -a android.intent.action.VIEW -d cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}" ``` To run the ADB command: 1. Plug your Android phone into your Computer (or use an emulator). 2. Make sure that only one phone or emulator is connected or running. 3. Start Android Studio. 4. Open the Terminal view. 5. Paste the ADB command into the Terminal and press `Enter`. 6. Switch to your phone or emulator and follow the steps on the screen. ### Contentsquare Log Visualizer Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log). Prerequisite To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings. 1. Start your app. 2. Select the Mobile icon in the menu top bar then select `Log Visualizer`. 3. Select the device to inspect. At this stage, you should see an 'App start' or 'App show' event being logged. ![Log visualizer Android app start](https://docs.contentsquare.com/_astro/log-visualizer-app-start.CjWWxzSe_1CiJ7F.webp) ## Get user consent Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked. ### User opt-in The SDK treats users as **opted-out by default.** To start tracking, forward user consent with `optIn()`. Calling this method generates a user ID and initiates tracking. Handle user consent by implementing a UI for privacy preferences. Assuming you have an opt-in screen with a button to give consent, the code could look like this: * Java ```java import com.contentsquare.android.Contentsquare; Button optinButton = ... optinButton.setOnClickListener(view -> { Contentsquare.optIn(); // Then finish initialization and move to the next screen... }); ``` * Kotlin ```kotlin import com.contentsquare.android.Contentsquare val optinButton: Button = ... optinButton.setOnClickListener { Contentsquare.optIn() // Then finish initialization and move to the next screen... } ``` Going further For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/android/privacy/). ## Track your first screens Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel. ### Sending screenview events Screen tracking is achieved by sending a `screenview` event each time a new screen is displayed on the user's device. To trigger a screenview each time an activity becomes visible, place the call in the `onResume()` method (XML layouts only): * Java ```java import com.contentsquare.android.Contentsquare; public class MyActivity extends Activity { @Override public void onResume() { super.onResume(); // Send screenView Contentsquare.send("screen_name"); } } ``` * Kotlin ```kotlin import com.contentsquare.android.Contentsquare class MyActivity : Activity() { override fun onResume() { super.onResume() // Send screenView Contentsquare.send("screen_name") } } ``` #### Jetpack Compose support To enable Jetpack Compose support, add a new dependency to your Gradle build file. * Groovy **build.gradle** ```groovy implementation 'com.contentsquare.android:compose:4.44.1' ``` * Kotlin **build.gradle.kts** ```kotlin implementation("com.contentsquare.android:compose:4.44.1") ``` Attention must be paid to recompositions. The call should be wrapped using `TriggeredOnResume` to ensure only one screenview is triggered when a given screen is presented to the user. ```kotlin import com.contentsquare.android.Contentsquare import com.contentsquare.android.compose.analytics.TriggeredOnResume @Composable fun MyComposable(data: Data) { TriggeredOnResume { Contentsquare.send("screen_name") } // ... } ``` ### Implementation recommendations From a functional perspective, a screenview should be triggered in the following cases: * When the screen appears on the device * When a modal or pop-up is displayed * When a modal or pop-up is closed, returning the user to the screen * When the app is brought back to the foreground (after being minimized) Specific triggers Depending on how your app is built (Popups, Webviews, Redirections, etc...), you might need specific implementation use cases for triggering screenview events. See the [dedicated section on screen tracking](https://docs.contentsquare.com/en/android/track-screens/#implementation-recommendations). #### Tracking app launch Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started. Refer to [our guide](https://docs.contentsquare.com/en/android/track-screens/#when-to-send-your-first-screenview) for implementation examples. #### Screen name handling It is necessary to provide a name for each screen when calling the screenview API. As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side. More on [screen name handling](https://docs.contentsquare.com/en/android/track-screens/#how-to-name-screens). Tracking plan To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used. ## Test your setup Testing your SDK implementation is essential to make sure data is being accurately captured and reported. To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform. You can also use debugging tools such as Android Studio or Log Visualizer to monitor data transmission and ensure everything is running smoothly. ### Visualize events in Contentsquare Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time. By simulating user activity, you see incoming screenview and gesture events. ![Log visualizer Android activity](https://docs.contentsquare.com/_astro/log-visualizer-activity.x9zqNXUC_3mvS0.webp) ### Visualize data in Contentsquare Data availability Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app. #### In Journey Analysis [Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen. ![](https://docs.contentsquare.com/_astro/check-data-journay-analysis.CjaeeRjK_1Iime.webp) See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161). #### In Session Replay [Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app. ![](https://docs.contentsquare.com/_astro/check-data-session-replay.Cvuj2X01_HiOzM.webp) See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561) ## Sample app To explore some of these features in context, check our Android sample app. ### [android-sample-app](https://github.com/ContentSquare/android-sample-app) [A sample app giving an example implementation of the Contentsquare SDK](https://github.com/ContentSquare/android-sample-app) [Kotlin](https://github.com/ContentSquare/android-sample-app) ## Next steps While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior. Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking. Proceed with these how-to's to refine your implementation. [Custom Variables ](https://docs.contentsquare.com/en/android/track-custom-variables/)Collect additional details about the screen or the user. [Dynamic Variables ](https://docs.contentsquare.com/en/android/track-dynamic-variables/)Collect additional information about the session. [Transactions tracking ](https://docs.contentsquare.com/en/android/track-transactions/)Associate user's session with their potential purchases and corresponding revenue. [WebViews ](https://docs.contentsquare.com/en/android/track-webviews/)For native apps which embark web applications or pages. [Session Replay ](https://docs.contentsquare.com/en/android/session-replay/)Collect data for Session Replay in compliance personal data masking. [Error Analysis ](https://docs.contentsquare.com/en/android/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools.