Engage SDK Cluster publishing guidelines

This guide includes a set of guidelines for cluster publishing that developers can use when integrating with Engage SDK.

Recommendation clusters

Cluster Title

We recommend providing a unique and relevant cluster title that gives users more insight on the content of the cluster.

Here are some examples of good cluster titles based on the content:

Shopping-related clusters
- Lightning Deals
- Weekly must buys
- Related to your purchase of Pixel Buds
- Women’s rain boots
Clusters of books on health
- Health, mind & body
- Recommended for you in Health
- Best-sellers in Fitness

Cluster Content

When publishing recommendation clusters, developers must consider whether or not the user is signed in to the developer's application.

When user is signed in

If the user is signed in to the developer app, we strongly recommend publishing personalized or user-generated content clusters. Because personalized and user-generated content is more relevant to the user, they are more motivated to visit the developer app from the Google surface.

Personalized recommendations can be published.
- Here are some examples of personalized recommendations:
  - Top picks based on the user's watch history.
  - Books similar to books that are in the user's read history.
  - Songs by the user's favorite artists.
User-generated content libraries can be published.
- Here are some examples of user-generated content libraries:
  - The user's watchlist from the developer app.
  - A self-reported list of the user's favorite artists from the developer app.

Recommendation type	Content freshness strategy	Content freshness guideline
Personalized recommendations	Lenient We strongly recommend updating the recommendations once per day so users can see new recommendations daily.	Because users do not have an exact expectation of what the recommendation content will be, the content freshness strategy can be lenient.
User-generated content libraries	Strict We strongly recommend updating the content library as users exit the developer app.	It's important for this content to be in sync with the data displayed on Google surfaces. This is because unlike personalized recommendations, the user expects an exact set of content. Any significant delay in publishing will confuse users. Therefore, the content freshness strategy must be strict.

Recommendation type

Content freshness strategy

Content freshness guideline

Personalized recommendations

Lenient

We strongly recommend updating the recommendations once per day so users can see new recommendations daily.

Because users do not have an exact expectation of what the recommendation content will be, the content freshness strategy can be lenient.

User-generated content libraries

Strict

We strongly recommend updating the content library as users exit the developer app.

It's important for this content to be in sync with the data displayed on Google surfaces. This is because unlike personalized recommendations, the user expects an exact set of content. Any significant delay in publishing will confuse users. Therefore, the content freshness strategy must be strict.

When user is not signed in

If a user is not signed in to the developer app, we still recommend publishing clusters so that users are encouraged to visit the developer app from the Google surface.

Non-personalized recommendation clusters should be published.
- Here are some examples of non-personalized recommendations:
  - Top 10 books read this year.
  - Newly released movies.
  - Trending podcasts.
Include a sign-in card in the recommendation cluster.
- In order to encourage users to sign in to the developer app, developers may choose to publish a sign-in card along with the non-personalized recommendation cluster.

Recommendation type	Content freshness strategy	Content freshness guideline
Non-personalized recommendations	Lenient We strongly recommend updating the recommendations once per day.	Because users do not have an exact expectation of what the recommendation content will be, the content freshness strategy can be lenient.
Sign-in card in recommendations	Strict We strongly recommend updating the sign-in card state in recommendations as users exit the developer app.	It's important for the sign-in state to be in sync with the Google surface. It's confusing for a user to see a sign-in card on Google's surface when they're already signed in. Therefore, the content freshness strategy must be strict.

Recommendation type

Content freshness strategy

Content freshness guideline

Non-personalized recommendations

Lenient

We strongly recommend updating the recommendations once per day.

Because users do not have an exact expectation of what the recommendation content will be, the content freshness strategy can be lenient.

Sign-in card in recommendations

Strict

We strongly recommend updating the sign-in card state in recommendations as users exit the developer app.

It's important for the sign-in state to be in sync with the Google surface. It's confusing for a user to see a sign-in card on Google's surface when they're already signed in. Therefore, the content freshness strategy must be strict.

Continuation clusters

When publishing continuation clusters, developers must consider whether or not the user is signed in to the developer's application.

When user is signed in

User-generated continuation clusters should be published.
- Here are some examples of user-generated continuation clusters:
  - Continue Watching from where the user left off.
  - Continue Reading from where the user left off.

Continuation type	Content freshness strategy	Content freshness guideline
User-generated continuation clusters	Strict We strongly recommend updating the content library as users exit the developer app.	It's important for this content to be in sync with the data displayed on Google's surfaces. This is because unlike personalized recommendations, the user expects an exact set of content. Any significant delay in publishing will confuse users. Therefore, the content freshness strategy must be strict.

Continuation type

Content freshness strategy

Content freshness guideline

User-generated continuation clusters

Strict

We strongly recommend updating the content library as users exit the developer app.

It's important for this content to be in sync with the data displayed on Google's surfaces. This is because unlike personalized recommendations, the user expects an exact set of content. Any significant delay in publishing will confuse users. Therefore, the content freshness strategy must be strict.

When user is not signed in

Because continuation journeys are intended for signed-in users, continuation clusters might not be published.

WorkManager for cluster publishing

We recommend using WorkManager to publish clusters, because it is the recommended solution for background work where the execution must be both opportunistic and guaranteed.

WorkManager performs your background work as soon as it can.
WorkManager handles the logic to start your work under a variety of conditions, even if a user navigates away from your app.

When the user navigates away from the app, we recommend starting a background job that publishes continuation clusters along with recommendation clusters. A good place to handle this logic is Activity.onStop(), which is called when the user navigates away from the app.

We suggest using PeriodicWorkRequest to schedule a recurring job that publishes clusters every 24 hours. By using a CANCEL_AND_REENQUEUE policy for triggering the work, developers can ensure that WorkManager sends the updated data every time a user navigates away from the app. This helps prevent users from seeing stale data.

The following example demonstrates this:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

Handle broadcast intents

In addition to making publish content API calls through a job, it is also required to set up a BroadcastReceiver to receive the request for a content publish.

However, developers must be careful not to rely solely on broadcasts, because they are only triggered in certain scenarios—mainly, for app reactivation and forcing a data sync. They are only triggered when the Engage Service determines that the content might be stale. That way, there is greater confidence that the user will have a fresh content experience, even if the application has not been opened for a long time.

The BroadcastReceiver must be set up in the following two ways:

Dynamically register an instance of the BroadcastReceiver class using Context.registerReceiver(). This enables communication from applications that are still live in memory.
Statically declare an implementation with the <receiver> tag in your AndroidManifest.xml file. This allows the application to receive broadcast intents when it is not running, and also allows the application to publish the content.