Update documentation for pillarbox-analytics

build-logic/plugins/src/main/java/ch/srgssr/pillarbox/gradle/PillarboxAndroidLibraryPublishingPlugin.kt

@@ -88,7 +88,11 @@ class PillarboxAndroidLibraryPublishingPlugin : Plugin<Project> {
 
         extensions.configure<DokkaExtension> {
             dokkaSourceSets.getByName("main") {
-                includes.from("Module.md")
+                if (file("Module.md").exists()) {
+                    includes.from("Module.md")
+                } else {
+                    includes.from("docs/README.md")
+                }
 
                 // This is currently broken in Dokka for Android modules. See: https://github.com/Kotlin/dokka/issues/2876
                 sourceLink {
@@ -104,7 +108,7 @@ class PillarboxAndroidLibraryPublishingPlugin : Plugin<Project> {
                 customStyleSheets.from(rootProject.projectDir.resolve("dokka/styles/pillarbox.css"))
                 footerMessage.set("© SRG SSR")
                 // TODO Enable this once we have some content there
-                // homepageLink.set("https://srgssr.github.io/pillarbox-android")
+                // homepageLink.set("https://android.pillarbox.ch/")
                 templatesDir.set(rootProject.projectDir.resolve("dokka/templates"))
             }
         }

build.gradle.kts

@@ -2,7 +2,6 @@
  * Copyright (c) SRG SSR. All rights reserved.
  * License information is available from the LICENSE file.
  */
-import org.jetbrains.dokka.gradle.tasks.DokkaGenerateTask
 
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
@@ -18,21 +17,21 @@ plugins {
     alias(libs.plugins.pillarbox.detekt)
 }
 
-tasks.withType<DokkaGenerateTask> {
-    generator.includes.from("dokka/Pillarbox.md")
-}
-
 dokka {
     moduleVersion = providers.environmentVariable("VERSION_NAME").orElse("dev")
 
+    dokkaPublications.html {
+        includes.from("dokka/Pillarbox.md")
+    }
+
     pluginsConfiguration.html {
         // See the overridable images here:
         // https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-base/src/main/resources/dokka/images
         customAssets.from("dokka/images/logo-icon.svg") // TODO Use Pillarbox logo
         customStyleSheets.from("dokka/styles/pillarbox.css")
         footerMessage.set("© SRG SSR")
         // TODO Enable this once we have some content there
-        // homepageLink.set("https://srgssr.github.io/pillarbox-android")
+        // homepageLink.set("https://android.pillarbox.ch/")
         templatesDir.set(file("dokka/templates"))
     }
 }

dokka/Pillarbox.md

@@ -11,4 +11,4 @@ It is split in multiple modules, whose documentation is available from the side
 - [GitHub repository](https://github.com/SRGSSR/pillarbox-android)
 - [Pillarbox releases](https://github.com/SRGSSR/pillarbox-android/releases)
 - [Pillarbox for Apple](https://swiftpackageindex.com/SRGSSR/pillarbox-apple)
-- [Pillarbox for the Web](https://srgssr.github.io/pillarbox-web/api)
+- [Pillarbox for the Web](https://web.pillarbox.ch/api/)

pillarbox-analytics/docs/README.md

@@ -1,95 +1,132 @@
-[![Pillarbox logo](https://github.com/SRGSSR/pillarbox-apple/blob/main/docs/README-images/logo.jpg)](https://github.com/SRGSSR/pillarbox-android)
-[![Last release](https://img.shields.io/github/v/release/SRGSSR/pillarbox-android?label=Release)](https://github.com/SRGSSR/pillarbox-android/releases)
-[![Android min SDK](https://img.shields.io/badge/Android-21%2B-34A853)](https://github.com/SRGSSR/pillarbox-android)
-[![License](https://img.shields.io/github/license/SRGSSR/pillarbox-android?label=License)](https://github.com/SRGSSR/pillarbox-android/blob/main/LICENSE)
+# Module pillarbox-analytics
 
-# Pillarbox Analytics module
+Provides SRG SSR implementation for [Commanders Act](https://www.commandersact.com/) and [ComScore](https://comscore.com/) to send page view events
+and custom events.
 
-Provides SRG SSR implementation for CommandersAct and ComScore to send page view events and custom events.
-
-Custom events are supported only with CommandersAct!
+**Note:** custom events are only supported with Commanders Act.
 
 ## Integration
 
-```gradle
-implementation("ch.srgssr.pillarbox:pillarbox-analytics:$LATEST_RELEASE_VERSION")
+To use this module, add the following dependency to your project's `build.gradle`/`build.gradle.kts` file:
+
+```kotlin
+implementation("ch.srgssr.pillarbox:pillarbox-analytics:<pillarbox_version>")
 ```
 
 ## Getting started
 
-### Configuration and create
+### Configure analytics
 
-Before using `SRGAnalytics` make sure to call `SRGAnalytics.init` first, otherwise it can lead to undefined behavior.
-It is strongly recommended to call the initializer inside your `Application.onCreate` method.
+Before using any functionality, [SRGAnalytics][ch.srgssr.pillarbox.analytics.SRGAnalytics] must be initialized in your
+[Application][android.app.Application]'s [onCreate()][android.app.Application.onCreate] method using either the
+[initSRGAnalytics()][ch.srgssr.pillarbox.analytics.SRGAnalytics.initSRGAnalytics] or the
+[SRGAnalytics.init()][ch.srgssr.pillarbox.analytics.SRGAnalytics.init] method and providing an
+[AnalyticsConfig][ch.srgssr.pillarbox.analytics.AnalyticsConfig] instance.
 
 ```kotlin
-class DemoApplication : Application() {
-
+class MyApplication : Application() {
     override fun onCreate() {
         super.onCreate()
-        
+
         val config = AnalyticsConfig(
             vendor = AnalyticsConfig.Vendor.SRG,
-            nonLocalizedApplicationName = "PillarboxDemo",
-            appSiteName = "pillarbox-demo-android",
-            sourceKey = AnalyticsConfig.SOURCE_KEY_SRG_DEBUG
+            appSiteName = "Your AppSiteName here",
+            sourceKey = AnalyticsConfig.SOURCE_KEY_SRG_DEBUG,
+            nonLocalizedApplicationName = "Your non-localized AppSiteName here",
         )
-
-        initSRGAnalytics(config = config)
+
+        initSRGAnalytics(config)
+        // or
+        SRGAnalytics.init(this, config)
     }
 }
 ```
 
 ### Handle user consent
 
-User consent can be configured at initialization, from your `Application` class:
+User consent can be configured when initializing analytics in your [Application][android.app.Application]'s
+[onCreate()][android.app.Application.onCreate] method:
+
 ```kotlin
-val initialUserConsent = UserConsent(
+val userConsent = UserConsent(
     comScore = ComScoreUserConsent.UNKNOWN,
-    commandersActConsentServices = emptyList()
+    commandersActConsentServices = emptyList(),
 )
 
 val config = AnalyticsConfig(
     vendor = AnalyticsConfig.Vendor.SRG,
-    nonLocalizedApplicationName = "PillarboxDemo",
-    appSiteName = "pillarbox-demo-android",
+    appSiteName = "Your AppSiteName here",
     sourceKey = AnalyticsConfig.SOURCE_KEY_SRG_DEBUG,
-    userConsent = initialUserConsent
+    nonLocalizedApplicationName = "Your non-localized AppSiteName here",
+    userConsent = userConsent,
 )
 
-initSRGAnalytics(config = config)
+initSRGAnalytics(config)
 ```
 
 Or it can be updated at any time using the following code snippet:
+
 ```kotlin
-val updatedUserConsent = UserConsent(
-    comScore = ComScoreUserConsent.DECLINED, // or ComScoreUserConsent.ACCEPTED
-    commandersActConsentServices = listOf("service1_id", "service2_id")
+val userConsent = UserConsent(
+    comScore = ComScoreUserConsent.DECLINED,
+    commandersActConsentServices = listOf("service1_id", "service2_id"),
 )
 
-SRGAnalytics.setUserConsent(updatedUserConsent)
+SRGAnalytics.setUserConsent(userConsent)
 ```
 
-User consent values will be updated with the next analytics event.
+The updated values will be sent with the next analytics event.
 
 ### Send page view
 
-To send a page view use `SRGAnalytics.sendPageView`. It will trigger a CommandersAct and a Comscore page view event directly.
+To send a page view, use [SRGAnalytics.sendPageView()][ch.srgssr.pillarbox.analytics.SRGAnalytics.sendPageView]. It will send the event to both
+Commanders Act and ComScore.
 
 ```kotlin
-val commandersActEvent = CommandersActPageView(name = "main", type = "tbd", levels = listOf("app", "pillarbox"))
-val comScoreEvent = ComScorePageView(name = "main")
-SRGAnalytics.sendPageView(commandersAct = commandersActEvent, comScore = comScoreEvent)
-```
+val commandersActPageView = CommandersActPageView(
+    name = "page_name",
+    type = "page_type",
+    levels = listOf("level1", "level2"),
+)
 
-In the case of a multi pane view each pane view can send a page view. It is useful then reusing view from single pane view inside the multi pane view.
+val comScorePageView = ComScorePageView(name = "page_name")
 
-For Android Auto application it is not recommended to send page view.
+SRGAnalytics.sendPageView(
+    commandersAct = commandersActPageView,
+    comScore = comScorePageView,
+)
+```
+
+In the case of a multi-pane view, each pane view can send a page view. It is useful when reusing views from a single pane view inside the multi-pane
+view.
+For Android Auto applications, it is not recommended to send page view.
 
 ### Send event
 
-Events are application events the analytics team of the application want to track. It could be click event, user choice etc..
+Events are application events that the analytics team wants to track. It could be a click event, a user choice, etc...
 
 ```kotlin
-SRGAnalytics.sendEvent(CommandersActEvent(name = "event"))
+val commandersActEvent = CommandersActEvent(name = "event")
+
+SRGAnalytics.sendEvent(commandersActEvent)
 ```
+
+# Package ch.srgssr.pillarbox.analytics
+
+Top-level entry point for managing analytics in Pillarbox for SRG SSR applications.
+
+# Package ch.srgssr.pillarbox.analytics.commandersact
+
+Commanders Act specific classes.
+
+# Package ch.srgssr.pillarbox.analytics.comscore
+
+ComScore specific classes.
+
+[android.app.Application]: https://developer.android.com/reference/kotlin/android/app/Application.html
+[android.app.Application.onCreate]: https://developer.android.com/reference/kotlin/android/app/Application.html#oncreate
+[ch.srgssr.pillarbox.analytics.AnalyticsConfig]: https://android.pillarbox.ch/api/pillarbox-analytics/ch.srgssr.pillarbox.analytics/-analytics-config/index.html
+[ch.srgssr.pillarbox.analytics.SRGAnalytics]: https://android.pillarbox.ch/api/pillarbox-analytics/ch.srgssr.pillarbox.analytics/-s-r-g-analytics/index.html
+[ch.srgssr.pillarbox.analytics.SRGAnalytics.init]: https://android.pillarbox.ch/api/pillarbox-analytics/ch.srgssr.pillarbox.analytics/-s-r-g-analytics/init.html
+[ch.srgssr.pillarbox.analytics.SRGAnalytics.initSRGAnalytics]: https://android.pillarbox.ch/api/pillarbox-analytics/ch.srgssr.pillarbox.analytics/-s-r-g-analytics/init-s-r-g-analytics.html
+[ch.srgssr.pillarbox.analytics.SRGAnalytics.sendPageView]: https://android.pillarbox.ch/api/pillarbox-analytics/ch.srgssr.pillarbox.analytics/-s-r-g-analytics/send-page-view.html

pillarbox-analytics/src/main/java/ch/srgssr/pillarbox/analytics/AnalyticsConfig.kt

@@ -4,17 +4,25 @@
  */
 package ch.srgssr.pillarbox.analytics
 
+import ch.srgssr.pillarbox.analytics.AnalyticsConfig.Companion.SOURCE_KEY_SRG_DEBUG
+import ch.srgssr.pillarbox.analytics.AnalyticsConfig.Companion.SOURCE_KEY_SRG_PROD
+import ch.srgssr.pillarbox.analytics.SRGAnalytics.initSRGAnalytics
+
 /**
- * SRG Analytics config
+ * Represents the configuration for analytics tracking for SRG SSR applications. This should be used in conjunction with
+ * [SRGAnalytics.initSRGAnalytics] or [SRGAnalytics.init].
+ *
+ * This class holds the necessary information for configuring analytics tracking, including the vendor, application details, user consent, and
+ * persistent labels.
  *
- * @property vendor business unit.
- * @property appSiteName The App/Site name given by the analytics team.
- * @property sourceKey The CommandersAct sourceKey given by the analytics team.
- * @property nonLocalizedApplicationName Application name for the analytics, by default the application name defined in the manifest. You can set
- * it to null if the application name is not localized.
- * @property userConsent User consent to transmit to ComScore and CommandersAct.
- * @property comScorePersistentLabels initial ComScore persistent labels.
- * @property commandersActPersistentLabels initial CommandersAct persistent labels.
+ * @property vendor The vendor to which the application belongs to.
+ * @property appSiteName The name of the app/site being tracked, given by the analytics team.
+ * @property sourceKey The CommandersAct source key. Production apps should use [SOURCE_KEY_SRG_PROD], and apps in development should use
+ * [SOURCE_KEY_SRG_DEBUG].
+ * @property nonLocalizedApplicationName The non-localized name of the application. By default, the application name defined in the manifest is used.
+ * @property userConsent The user consent to transmit to ComScore and CommandersAct.
+ * @property comScorePersistentLabels The initial persistent labels for ComScore analytics.
+ * @property commandersActPersistentLabels The initial persistent labels for Commanders Act analytics.
  */
 data class AnalyticsConfig(
     val vendor: Vendor,
@@ -25,9 +33,8 @@ data class AnalyticsConfig(
     val comScorePersistentLabels: Map<String, String>? = null,
     val commandersActPersistentLabels: Map<String, String>? = null,
 ) {
-
     /**
-     * Vendor
+     * Represents the different vendors supported by the application.
      */
     @Suppress("UndocumentedPublicProperty")
     enum class Vendor {
@@ -42,12 +49,12 @@ data class AnalyticsConfig(
     @Suppress("UndocumentedPublicClass")
     companion object {
         /**
-         * SRG Production CommandersAct source key
+         * The source key for SRG SSR apps in production.
          */
         const val SOURCE_KEY_SRG_PROD = "3909d826-0845-40cc-a69a-6cec1036a45c"
 
         /**
-         * SRG Debug CommandersAct source key
+         * The source key for SRG SSR apps in development.
          */
         const val SOURCE_KEY_SRG_DEBUG = "6f6bf70e-4129-4e47-a9be-ccd1737ba35f"
     }