Engage SDK Integration

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.)
        }
    }
}

<!--    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>

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
        }
    }
}

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()
}

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)
    }
}

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"
}

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()
    }
}

[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" }

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()
}

<!-- Mandatory for TV integrations -->
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

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()
)

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()