reis-mobile 0.3.6 → 0.5.0

package/skills/mobile-android/references/play/engage-sdk-integration/references/patterns.md

@@ -0,0 +1,527 @@
+## EngageBroadcastReceiver
+
+Setting up the `BroadcastReceiver` correctly requires **both** static and
+dynamic registration. Static registration allows the app to receive broadcasts
+even when it isn't running, while dynamic registration is required on newer
+Android versions to safely receive broadcasts when the app is live in memory.
+
+### BroadcastReceiver implementation
+
+
+```kotlin
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import androidx.core.content.ContextCompat
+import com.google.android.engage.service.BroadcastReceiverPermissions
+
+class EngageBroadcastReceiver : BroadcastReceiver() {
+    // IMPORTANT: Only trigger the specific publish job for the received intent action.
+    // DO NOT publish all clusters at once.
+    override fun onReceive(context: Context?, intent: Intent?) {
+        if (intent == null || context == null) return
+        when (intent.action) {
+            com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION
+            -> EngagePublisher.publishOneTime(context, Constants.PUBLISH_TYPE_RECOMMENDATIONS)
+            // Note: If app handles other publish actions (e.g. Featured, Continuation), add them here.
+            com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED
+            -> EngagePublisher.publishOneTime(context, Constants.PUBLISH_TYPE_FEATURED)
+
+            /** Note: If vertical has other intents (e.g. FOOD shopping cart, etc.), add them here.
+             * com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART
+             * -> EngagePublisher.publishOneTime(context, Constants.PUBLISH_TYPE_FOOD_SHOPPING_CARD)
+             * com.google.android.engage.travel.service.Intents.ACTION_PUBLISH_RESERVATION
+             * -> EngagePublisher.publishOneTime(context, Constants.PUBLISH_TYPE_RESERVATION )
+             **/
+        }
+    }
+
+    companion object {
+        /**
+         * Dynamically registers the receiver.
+         * This is required in addition to static registration in AndroidManifest.xml.
+         * Call this method in your Application's onCreate() or your main Activity's onCreate().
+         */
+        fun register(context: Context) {
+            val appContext = context.applicationContext
+            val receiver = EngageBroadcastReceiver()
+
+            // Register Cluster Publish Intents
+            val filter = IntentFilter().apply {
+                addAction(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION)
+                addAction(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED)
+                addAction(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION)
+            }
+            ContextCompat.registerReceiver(
+                appContext,
+                receiver,
+                filter,
+                BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
+                null,
+                ContextCompat.RECEIVER_EXPORTED
+            )
+            // Note: Add vertical-specific intents here if applicable (e.g., FOOD shopping cart, etc.)
+        }
+    }
+}
+```
+
+<br />
+
+### Static registration in AndroidManifest.xml
+
+Add the `<receiver>` tag inside the `<application>` block in
+`AndroidManifest.xml`
+
+
+```xml
+<!--    Add the `<receiver>` tag inside the `<application>` block in `AndroidManifest.xml`:-->
+<receiver
+    android:name="com.example.snippets.engage.EngageBroadcastReceiver"
+    android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
+    android:exported="true"
+    android:enabled="true">
+    <!-- Recommended for production TV APKs -->
+    <intent-filter>
+        <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
+        <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
+        <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
+        <!-- Note: Add vertical-specific intents here if applicable (e.g., FOOD shopping cart, etc.) -->
+    </intent-filter>
+</receiver>
+```
+
+<br />
+
+## EngageWorker
+
+
+```kotlin
+import android.content.Context
+import android.util.Log
+import androidx.work.CoroutineWorker
+import androidx.work.WorkerParameters
+import com.google.android.engage.common.datamodel.ClusterType
+import com.google.android.engage.service.AppEngageErrorCode
+import com.google.android.engage.service.AppEngageException
+import com.google.android.engage.service.AppEngagePublishClient
+import com.google.android.engage.service.AppEngagePublishStatusCode
+import com.google.android.engage.service.PublishStatusRequest
+import com.google.android.engage.service.ServiceAvailabilityRequest
+import com.google.android.gms.tasks.Task
+import kotlinx.coroutines.tasks.await
+
+class EngageWorker(context: Context, workerParams: WorkerParameters) : CoroutineWorker(context, workerParams) {
+    // Replace {AppEngagePublishClient} with the "client" class found in references/schemas/{VERTICAL}.md.
+    // Client class can vary based on app's vertical.
+    // Refer to the references/schemas/{VERTICAL}.md to find the right class.
+    // This is an example of using AppEngagePublishClient.
+    private val client = AppEngagePublishClient(context)
+    private val clusterRequestFactory = ClusterRequestFactory(context)
+
+    override suspend fun doWork(): Result {
+        if (runAttemptCount > Constants.MAX_PUBLISHING_ATTEMPTS) {
+            // If we keep failing, report it as a service error before giving up.
+            updatePublishStatus(AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR)
+            return Result.failure()
+        }
+
+        val publishType = inputData.getString(Constants.PUBLISH_TYPE_KEY)
+        val intendedClusterType = when (publishType) {
+            Constants.PUBLISH_TYPE_RECOMMENDATIONS -> ClusterType.TYPE_RECOMMENDATION
+            Constants.PUBLISH_TYPE_FEATURED -> ClusterType.TYPE_FEATURED
+            Constants.PUBLISH_TYPE_CONTINUATION -> ClusterType.TYPE_CONTINUATION
+            Constants.PUBLISH_TYPE_USER_ACCOUNT_MANAGEMENT -> ClusterType.TYPE_ENGAGEMENT
+            else -> ClusterType.TYPE_UNKNOWN
+        }
+
+        if (intendedClusterType != ClusterType.TYPE_UNKNOWN) {
+            val request = ServiceAvailabilityRequest.Builder()
+                .addIntendedClusterType(intendedClusterType)
+                .build()
+            val availabilityMap = client.isServiceAvailable(request).await()
+            if (availabilityMap[intendedClusterType] != true) {
+                return Result.failure()
+            }
+        }
+
+        return when (publishType) {
+            Constants.PUBLISH_TYPE_RECOMMENDATIONS -> publishRecommendations()
+            // Constants.PUBLISH_TYPE_FEATURED -> publishFeatured()
+            Constants.PUBLISH_TYPE_CONTINUATION -> publishContinuation()
+            Constants.PUBLISH_TYPE_USER_ACCOUNT_MANAGEMENT -> publishUserAccountManagement()
+            else -> Result.failure()
+        }
+    }
+
+    // Use similar patterns for other clusters (Featured, Continuation, FoodShoppingList, Reservation etc.)
+    private suspend fun publishRecommendations(): Result {
+        val publishTask: Task<Void> =
+            client.publishRecommendationClusters(
+                clusterRequestFactory.constructRecommendationClustersRequest()
+            )
+        return publishAndProvideResult(publishTask)
+    }
+
+    private suspend fun publishContinuation(): Result {
+        // Empty Continuation Guard: If there is no continuation content,
+        // we must delete the cluster instead of publishing an empty one on the UI.
+        if (getContinuationData().isEmpty()) {
+            val deleteTask = client.deleteContinuationCluster()
+            return publishAndProvideResult(deleteTask)
+        }
+
+        val publishTask: Task<Void> =
+            client.publishContinuationCluster(
+                clusterRequestFactory.constructContinuationClusterRequest()
+            )
+        return publishAndProvideResult(publishTask)
+    }
+
+    private suspend fun publishUserAccountManagement(): Result {
+        val publishTask: Task<Void>
+        if (isAccountSignedIn()) {
+            // If signed in, we delete the sign-in card.
+            publishTask = client.deleteUserManagementCluster()
+            return publishAndProvideResult(publishTask)
+        } else {
+            // If not signed in, we publish the sign-in card.
+            // Note: Even though we are publishing a card, the status code is NOT_PUBLISHED_REQUIRES_SIGN_IN
+            // because the actual content (recommendations/continuation) is not published.
+            publishTask =
+                client.publishUserAccountManagementRequest(
+                    clusterRequestFactory.constructUserAccountManagementClusterRequest()
+                )
+            return try {
+                publishTask.await()
+                updatePublishStatus(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
+                Result.success()
+            } catch (publishException: Exception) {
+                handlePublishException(publishException)
+            }
+        }
+    }
+
+    private fun isAccountSignedIn(): Boolean {
+        // Implement your app's sign-in check logic here.
+        // ...
+    }
+
+    private fun getContinuationData(): List<Any> {
+        // Implement your app's data loading logic here.
+        // ...
+    }
+
+    private suspend fun publishAndProvideResult(
+        publishTask: Task<Void>
+    ): Result {
+        return try {
+            // An AppEngageException may occur while publishing, so we may not be able to await the result.
+            publishTask.await()
+            // Update status to PUBLISHED only after successful publication.
+            updatePublishStatus(AppEngagePublishStatusCode.PUBLISHED)
+            Result.success()
+        } catch (publishException: Exception) {
+            handlePublishException(publishException)
+        }
+    }
+
+    private fun handlePublishException(publishException: Exception): Result {
+        val appEngageException = publishException as? AppEngageException
+        if (appEngageException != null) {
+            logPublishing(appEngageException)
+
+            // Map AppEngageException error codes to PublishStatusCodes
+            val errorStatusCode = when (appEngageException.errorCode) {
+                AppEngageErrorCode.SERVICE_CALL_INVALID_ARGUMENT ->
+                    AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR
+
+                AppEngageErrorCode.SERVICE_CALL_PERMISSION_DENIED ->
+                    AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR
+
+                else ->
+                    AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR
+            }
+            updatePublishStatus(errorStatusCode)
+
+            // Some errors are recoverable, such as a threading issue, some are unrecoverable
+            // such as a cluster not containing all necessary fields. If an error is recoverable, we
+            // should attempt to publish again. Setting the result to retry means WorkManager will
+            // attempt to run the worker again, thus attempting to publish again.
+            return if (isErrorRecoverable(appEngageException)) Result.retry() else Result.failure()
+        }
+        return Result.failure()
+    }
+
+    private fun updatePublishStatus(statusCode: Int) {
+        client
+            .updatePublishStatus(PublishStatusRequest.Builder().setStatusCode(statusCode).build())
+            .addOnSuccessListener {
+                Log.i(TAG, "Successfully updated publish status code to $statusCode")
+            }
+            .addOnFailureListener { exception ->
+                Log.e(TAG, "Failed to update publish status code to $statusCode\n${exception.stackTrace}")
+            }
+    }
+
+    private fun logPublishing(publishingException: AppEngageException) {
+        val message = when (publishingException.errorCode) {
+            AppEngageErrorCode.SERVICE_NOT_FOUND -> "Service not found"
+            AppEngageErrorCode.SERVICE_CALL_EXECUTION_FAILURE -> "Execution failure"
+            AppEngageErrorCode.SERVICE_NOT_AVAILABLE -> "Service not available"
+            AppEngageErrorCode.SERVICE_CALL_PERMISSION_DENIED -> "Permission denied"
+            AppEngageErrorCode.SERVICE_CALL_INVALID_ARGUMENT -> "Invalid argument"
+            AppEngageErrorCode.SERVICE_CALL_INTERNAL -> "Internal error"
+            AppEngageErrorCode.SERVICE_CALL_RESOURCE_EXHAUSTED -> "Resource exhausted"
+            else -> "Unknown error"
+        }
+        Log.d(TAG, message)
+    }
+
+    private fun isErrorRecoverable(publishingException: AppEngageException): Boolean {
+        return when (publishingException.errorCode) {
+            // Recoverable Error codes
+            AppEngageErrorCode.SERVICE_CALL_EXECUTION_FAILURE,
+            AppEngageErrorCode.SERVICE_CALL_INTERNAL,
+            AppEngageErrorCode.SERVICE_CALL_RESOURCE_EXHAUSTED -> true
+            // Non recoverable error codes
+            AppEngageErrorCode.SERVICE_NOT_FOUND,
+            AppEngageErrorCode.SERVICE_CALL_INVALID_ARGUMENT,
+            AppEngageErrorCode.SERVICE_CALL_PERMISSION_DENIED,
+            AppEngageErrorCode.SERVICE_NOT_AVAILABLE -> false
+            else -> false
+        }
+    }
+}
+```
+
+<br />
+
+## ClusterRequestFactory
+
+
+```kotlin
+class ClusterRequestFactory(context: Context) {
+
+    // ...
+
+    private val signInCard =
+        com.google.android.engage.common.datamodel.SignInCardEntity.Builder()
+            .addPosterImage(
+                com.google.android.engage.common.datamodel.Image.Builder()
+                    .setImageUri(Uri.parse("http://www.x.com/image.png"))
+                    .setImageHeightInPixel(500)
+                    .setImageWidthInPixel(500)
+                    .build()
+            )
+            .setActionText(signInCardAction)
+            .setActionUri(Uri.parse("https://xyz.com/signin"))
+            .build()
+
+    fun constructRecommendationClustersRequest(): com.google.android.engage.service.PublishRecommendationClustersRequest {
+
+        val items = appDataRepository.getRecommendations()
+        val recommendationCluster = com.google.android.engage.common.datamodel.RecommendationCluster.Builder()
+            .setTitle("Recommended Content") // Required field
+            .setRecommendationClusterType(com.google.android.engage.common.datamodel.RecommendationClusterType.TYPE_TOP_PICKS_FOR_YOU) // Required field
+        for (item in items) {
+            recommendationCluster.addEntity(ItemToEntityConverter.convert(item))
+        }
+        return com.google.android.engage.service.PublishRecommendationClustersRequest.Builder()
+            .addRecommendationCluster(recommendationCluster.build())
+            .setAccountProfile(accountProfile) // Set the account profile on the request for personalization/sync
+            .build()
+    }
+
+    fun constructContinuationClusterRequest(): com.google.android.engage.service.PublishContinuationClusterRequest {
+        val items = appDataRepository.getContinuationData()
+
+        val continuationCluster = com.google.android.engage.common.datamodel.ContinuationCluster.Builder()
+            .setAccountProfile(accountProfile) // Set the account profile on the request for personalization/sync
+
+        for (item in items) {
+            continuationCluster.addEntity(ItemToEntityConverter.convert(item))
+        }
+        return com.google.android.engage.service.PublishContinuationClusterRequest.Builder()
+            .setContinuationCluster(continuationCluster.build())
+            .build()
+    }
+
+    fun constructUserAccountManagementClusterRequest(): com.google.android.engage.service.PublishUserAccountManagementRequest =
+        com.google.android.engage.service.PublishUserAccountManagementRequest.Builder()
+            .setSignInCardEntity(signInCard)
+            .build()
+}
+```
+
+<br />
+
+## EngagePublisher
+
+
+```kotlin
+object EngagePublisher {
+
+    fun publishPeriodically(context: Context, publishType: String) {
+        val workRequest = PeriodicWorkRequestBuilder<EngageWorker>(Constants.REPEAT_INTERVAL, TimeUnit.HOURS)
+            .setInputData(workDataOf(Constants.PUBLISH_TYPE_KEY to publishType))
+            .build()
+        WorkManager.getInstance(context).enqueueUniquePeriodicWork("EngagePeriodic", ExistingPeriodicWorkPolicy.KEEP, workRequest)
+    }
+
+    fun publishOneTime(context: Context, publishType: String) {
+
+        val workRequest = OneTimeWorkRequestBuilder<EngageWorker>()
+            .setInputData(workDataOf(Constants.PUBLISH_TYPE_KEY to publishType))
+            .build()
+        WorkManager.getInstance(context).enqueueUniqueWork("EngageOneTime", ExistingWorkPolicy.REPLACE, workRequest)
+    }
+}
+```
+
+<br />
+
+## Constants
+
+
+```kotlin
+object Constants {
+    // Holds common values like attempt counts, publish types etc.
+    const val REPEAT_INTERVAL = 24L
+    const val MAX_PUBLISHING_ATTEMPTS = 3
+    const val PUBLISH_TYPE_KEY = "PUBLISH_TYPE"
+    const val PUBLISH_TYPE_RECOMMENDATIONS = "RECOMMENDATIONS"
+    const val PUBLISH_TYPE_FEATURED = "FEATURED"
+    const val PUBLISH_TYPE_CONTINUATION = "CONTINUATION"
+    // ...
+    const val PUBLISH_TYPE_USER_ACCOUNT_MANAGEMENT = "USER_ACCOUNT_MANAGEMENT"
+    // const val PUBLISH_TYPE_FOOD_SHOPPING_CARD = "FOOD_SHOPPING_CARD"
+    // const val PUBLISH_TYPE_RESERVATION = "RESERVATION"
+}
+```
+
+<br />
+
+## ItemToEntityConverter
+
+
+```kotlin
+object ItemToEntityConverter {
+    // Converts app's local models to appropriate engage entity models.
+    // Use `{VERTICAL}.md` in the `references/schemas/` directory to identify the correct Engage entities.
+    // This is an example of using EbookEntity model.
+    fun convert(item: AppData): EbookEntity {
+        return EbookEntity.Builder()
+            // Implement required data mapping logic here.
+            .setName(item.title)
+            .addAuthor(item.author)
+            .build()
+    }
+}
+```
+
+<br />
+
+> **Strict image aspect ratio requirement** : Play Engage has strict
+> requirements for image aspect ratios depending on the vertical and entity type
+> (e.g., 16:9 for landscape, 1:1 for square, 2:3 for portrait). Ensure your
+> `ItemToEntityConverter` maps images that conform to these strict requirements
+> to avoid cropping or content rejection by Play.
+
+## Dependency specifications (libs.versions.toml)
+
+This skill specifies all dependencies using the `libs.versions.toml` format.
+Adapt these definitions to other formats (such as standard Groovy `build.gradle`
+or Kotlin DSL `build.gradle.kts` implementation lines) as required by the
+project.
+
+    [versions]
+    engage-core = "1.6.0"
+    engage-tv = "1.1.0"
+    playServicesOssLicenses = "17.5.1"
+    workManager = "2.11.2"
+    coroutines = "1.10.2"
+
+    [libraries]
+    engage-core = { group = "com.google.android.engage", name = "engage-core", version.ref = "engage-core" }
+    engage-tv = { group = "com.google.android.engage", name = "engage-tv", version.ref = "engage-tv" }
+    play-services-oss-licenses = { group = "com.google.android.gms", name = "play-services-oss-licenses", version.ref = "playServicesOssLicenses" }
+    androidx-work-runtime-ktx = { group = "androidx.work", name = "work-runtime-ktx", version.ref = "workManager" }
+    androidx-work-testing = { group = "androidx.work", name = "work-testing", version.ref = "workManager" }
+    kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
+    kotlinx-coroutines-play-services = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-play-services", version.ref = "coroutines" }
+    kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutines" }
+
+## Dual content rating fields for Watch and TV
+
+For Watch and TV integrations, you must populate both the new `contentRatings`
+(which uses `RatingSystem`) and the legacy `contentRatingsLegacies` (which uses
+`String` lists) to ensure compatibility across all Google Play surfaces.
+
+
+```kotlin
+fun convertMovie(movie: MovieData): MovieEntity {
+    val ratingSystem = RatingSystem.Builder()
+        .setAgencyName("MPAA")
+        .setRating("PG-13")
+        .build()
+    return MovieEntity.Builder()
+        .setEntityId(movie.id)
+        .setName(movie.title)
+        // ... other fields
+        .addContentRating(ratingSystem) // Recommended API
+        .addContentRatingsLegacy(listOf("MPAA:PG-13")) // Legacy API for backward compatibility
+        .build()
+}
+```
+
+<br />
+
+## TV integrations
+
+The following patterns and configurations are specific to Android TV
+integrations.
+
+### AndroidManifest.xml for TV
+
+
+```xml
+<!-- Mandatory for TV integrations -->
+<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
+```
+
+<br />
+
+### PlatformSpecificUri example
+
+
+```kotlin
+val platformSpecificPlaybackUris = listOf(
+    com.google.android.engage.common.datamodel.PlatformSpecificUri.Builder()
+        .setPlatformType(com.google.android.engage.common.datamodel.PlatformType.TYPE_ANDROID_TV)
+        .setActionUri(Uri.parse("https://www.example.com/tv/play/123"))
+        .build(),
+    com.google.android.engage.common.datamodel.PlatformSpecificUri.Builder()
+        .setPlatformType(com.google.android.engage.common.datamodel.PlatformType.TYPE_ANDROID_MOBILE)
+        .setActionUri(Uri.parse("https://www.example.com/mobile/play/123"))
+        .build()
+)
+```
+
+<br />
+
+### AccountProfile example
+
+
+```kotlin
+val accountProfile: AccountProfile
+    get() = AccountProfile.Builder()
+        .setAccountId("user_123")
+        .setProfileId("profile_456")
+        // AppCompatDelegate.getApplicationLocales().get(0) for Per-App Language Preferences
+        .setLocale(Locale.getDefault().toLanguageTag())
+        .build()
+```
+
+<br />