tt/VibeCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

skill: add Android skills

Browse Source
This commit is contained in:
tongtongstudio
2026-07-14 10:34:54 +08:00
parent e260c02629
commit ab82fb7cf0
182 changed files with 62992 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
.agents/skills/engage-sdk-integration/SKILL.md Normal file
View File

@@ -0,0 +1,129 @@
---
name: engage-sdk-integration
description: Helps developers integrate, debug, and resolve Play Engage SDK implementation
issues. Use when adding Engage SDK support, generating publishing code, mapping
data classes to entities, or fixing SDK-related errors.
license: Complete terms in LICENSE.txt
metadata:
author: Google LLC
last-updated: '2026-07-09'
keywords:
- android
- engage
- engage sdk
- play engage library
- google play
---
This skill guides you through integrating the Play Engage SDK into an Android
app. It ensures that the code follows the mandatory structure and uses the
required Engage entities for each vertical.
## Workflow
Follow these steps to assist the developer:
1. **Identify Vertical and Cluster:**
- Ask the developer which vertical their app belongs to based on **[references/schemas/](references/schemas)**.
- Check if the integration is for TV or Mobile. Read the TV-specific sections in [patterns.md](references/patterns.md) as well if the integration is for TV.
- Use `{VERTICAL}.md` in the **[references/schemas/](references/schemas)** directory to identify the corresponding Engage entities and the `client` class name. The `client` field in the JSON provides the full class name. (e.g., `com.google.android.engage.food.service.AppEngageFoodClient`).
- **Note:** Initializing the client class requires a `Context` parameter (e.g., `AppEngageFoodClient(context)`).
- Always refer to [common.md](references/common.md) for common entities.
- Ask which cluster type they want to publish from the supported cluster types for that vertical.
- Find the method to call from `{VERTICAL}.md` in the **[references/schemas/](references/schemas)** directory for the specified cluster. Each method will specify the request it expects.
- Get the request structure from [requests.md](references/requests.md) and clusters from [clusters.md](references/clusters.md). Then suggest and use sources to fill the fields in the request structure correctly, along with the required entities and clusters.
2. **Generate Structured Boilerplate Code:**
- Create a new directory for all Engage-related code. Name the directory to match the naming convention of the existing codebase.
- Generate the following classes using templates in [patterns.md](references/patterns.md):
- `Constants`: Holds constant values like attempt counts, publish types.
- `ItemToEntityConverter`: Converts app's local models to Engage's Entity models.
- `ClusterRequestFactory`: Constructs the publish requests.
- `EngageWorker`: Handles the actual publishing and publish errors using WorkManager.
- `EngagePublisher`: Orchestrates periodic and one-time jobs.
- `EngageBroadcastReceiver`: Listens for AppEngageService intents and starts a one-time publish job from `EngagePublisher`. **Important** : Implement both **static registration** and **dynamic registration** patterns, including the companion object `register` method inside the `EngageBroadcastReceiver` class.
3. **Suggest Entity Mapping:**
- Ask the developer to provide their local model schema(e.g., a data class or a JSON snippet).
- If they haven't provided one, share entities from `{VERTICAL}.md` in the **[references/schemas/](references/schemas)** directory as a guide.
- Once the local model is identified, suggest a mapping to the corresponding Engage entity.
- Generate the conversion logic using the `ItemToEntityConverter` pattern in [patterns.md](references/patterns.md) and add it to the generated `{ENGAGE_CODE_DIR}/ItemToEntityConverter`
4. **Suggest Data Source:**
- Ask the developer to provide the source of actual data you'll publish.
- Once the source of data is identified, use the source of data to fetch data in app's local model schema.
- Use `{ENGAGE_CODE_DIR}/ItemToEntityConverter` to convert this data to Engage entity.
- Use obtained Engage entity model data with `{ENGAGE_CODE_DIR}/
ClusterRequestFactory` to get cluster requests.
- Call corresponding cluster publishing method obtained from `{VERTICAL}.md` in the **[references/schemas/](references/schemas)** directory with the obtained request in previous step in `{ENGAGE_CODE_DIR}/EngageWorker`.
5. **Gradle and Manifest Updates:**
- Suggest updates to `build.gradle` and `AndroidManifest.xml`.
- For mobile apps, use [patterns.md](references/patterns.md).
- For TV apps, use the TV-specific sections in [patterns.md](references/patterns.md).
- Provide the necessary `implementation` dependencies for `build.gradle` or `build.gradle.kts` from [patterns.md](references/patterns.md).
- Provide the `<receiver>` and `<service>` declarations for `AndroidManifest.xml`.
- Note: There's no separate import according to vertical except TV. For each vertical other than TV 'com.google.android.engage:engage-core:1.5.12' is enough.
6. **Debugging:**
- Perform a Gradle sync.
- If errors occur, follow this resolution order:
- Fix import errors. For package `com.google.android.engage` or classes starting with `AppEngage`, verify the package name in the `{VERTICAL}.md` in **[references/schemas/](references/schemas)** directory or [common.md](references/common.md).
- Fix any other errors.
- Execute a full Gradle build and resolve any remaining compilation issues. Repeat this step until the Gradle build is successful.
7. **User Checklist:**
At the end of code generation, notify the user to go through this checklist
to verify that the integration is complete and as intended:
\[ \] Verify that all the engage related files are created in
`{ENGAGE_CODE_DIR}/`:
- `Constants`
- `ItemToEntityConverter`
- `ClusterRequestFactory`
- `EngageWorker`
- `{cluster_type}Publisher`
- `EngageBroadcastReceiver`
\[ \] Verify that app's local model is converted to Engage entity by populating
the fields correctly in the model in `{ENGAGE_CODE_DIR}/
ItemToEntityConverter`.
\[ \] Verify that `{ENGAGE_CODE_DIR}/EngageWorker` uses the data source
identified in Step 4.
\[ \] Verify that `EngageBroadcastReceiver.register(context)` is called within
the `Application` class or `MainActivity` to register the receiver
dynamically.
\[ \] Verify that `AndroidManifest.xml` contains the static `<receiver>`
declaration for `EngageBroadcastReceiver` with the necessary intent actions.
- **Important** : Explicitly instruct the developer to call `EngageBroadcastReceiver.register(context)` inside their custom `Application` class `onCreate()` (or their main activity `onCreate()`) to dynamically register the receiver. Stress that **both** static and dynamic registrations are required for the integration to function.
## Reference Materials
- **FAQ:** [Engage FAQ](references/android/guide/playcore/engage/faq.md) - Refer to this document for answers to frequently
asked questions from developers.
- **Vertical-Specific Guides:**
- [Food Vertical](references/android/guide/playcore/engage/food.md)
- [Watch Vertical](references/android/guide/playcore/engage/watch.md)
- [Listen Vertical](references/android/guide/playcore/engage/listen.md)
- [Read Vertical](references/android/guide/playcore/engage/read.md)
- [Shopping Vertical](references/android/guide/playcore/engage/shopping.md)
- [Social Vertical](references/android/guide/playcore/engage/social.md)
- [Travel Vertical](references/android/guide/playcore/engage/travel.md)
- [Health \& Fitness Vertical](references/android/guide/playcore/engage/healthandfitness.md)
- [Other Verticals](references/android/guide/playcore/engage/otherverticals.md)
- [TV Getting Started](references/android/guide/playcore/engage/tv/getting-started.md)
- [TV Recommendations](references/android/guide/playcore/engage/tv/recommendations.md)
- [TV Continue Watching](references/android/guide/playcore/engage/tv/continue-watching/index.md)
- [TV Entitlements](references/android/guide/playcore/engage/tv/entitlements.md)
- **Vertical-Specific Schemas:**
- [Food Schema](references/schemas/food.md)
- [Watch Schema](references/schemas/watch.md)
- [Listen Schema](references/schemas/listen.md)
- [Read Schema](references/schemas/read.md)
- [Shopping Schema](references/schemas/shopping.md)
- [Social Schema](references/schemas/social.md)
- [Travel Schema](references/schemas/travel.md)
- [TV Schema](references/schemas/tv.md)
- [Other Schema](references/schemas/other.md)

439
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/faq.md Normal file
View File

@@ -0,0 +1,439 @@
## Publish FAQs
#### Who manages the content publishing job?
The app developer manages the content publishing job and sends requests to the
Engage Service. In this way, developer partners have more control over when and
how to publish content to the users. This avoids waking up the partner app too
frequently to publish content.
#### Does a developer need to publish all cluster types?
While technically developers are free to publish just one cluster, we **strongly
advise** including more. Otherwise, developers miss the opportunity to drive
better engagement with their content. We **highly recommend** publishing all
cluster types for each vertical.
#### How often should the developer partner be publishing data using the work manager while the app is running?
This is to be decided by the developer partner. Google recommends publishing
once or twice per day for general recommendation content, and to use an
event-driven methodology for shopping cart, reorder, and other continuation
content (for example, start the worker as a callback of the user adding items
to the cart or the user stopping a movie halfway).
For **social** apps, it's critical to publish updated recommendation clusters
**after each app usage**. Social app users are more interested in the most
recent recommendations and ideally would like to see a post at most once.
#### When should the developer call delete APIs?
Delete APIs should only be called when there is no content to publish. **Don't**
call delete and publish APIs subsequently to replace content; the publish
APIs remove the earlier content automatically.
## Broadcast Intent FAQs
#### Why do Android app developers need to register for broadcast intents?
In order to serve fresh content to the user, you should use broadcast intents to
trigger a data sync in cases where users might not use the app frequently.
#### Unable to test broadcast intent
The verification app doesn't support testing broadcast intent with
permission. You have to remove permissions while testing and
add them back before switching the SDK to prod version in [Step 6](https://developer.android.com/guide/playcore/engage/workflow#switch-to-prod).
#### Background execution not allowed
While registering the broadcast intent, you may come across the following error:
Background execution not allowed: receiving Intent
{ act=com.google.android.engage.action.PUBLISH_RECOMMENDATION .. }
You need to register the broadcast receivers dynamically.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
}
public static void registerBroadcastReceivers(Context context) {
context = context.getApplicationContext();
// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION,
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null));
...
}
## Workflow FAQs
While integrating with the SDK, you may come across the following errors:
#### Validation errors at the app, cluster, entity level
Summaries at the app, cluster, and entity levels display a count of
validation errors. These errors correspond to missing required fields or
invalid values provided. Error messages show up in red beneath each relevant
field. Fix all validation errors and check for correctness before sharing
the APK.
#### Testing Deep links
The deep links are associated with the package name. A good way to test
deep links is using the adb tool.
adb shell am start -W -a android.intent.action.VIEW -d <DEEPLINK URI> <PACKAGE NAME>
#### How can I calculate the impact of the integration?
The deep links are a great way to track the attribution. The deep link URLs
that take users to your app can be included with additional tracking params.
For example - "http://xx/deeplink?source_tag=engage".
Developers can add their own tracking params and provide attribution to
calculate impact.
## Engage for TV 2.0 FAQs
### General Questions
#### What is Engage?
Engage takes the "pick up where you left off" experience to the next level! It's
a significant upgrade that allows viewers to seamlessly resume their content
across a wider range of devices. Imagine starting a movie on your Google TV and
then effortlessly continuing it on your phone during your commute -- that's the
power of Engage.
This new system is designed to boost viewer engagement and retention by
providing a smooth, frictionless experience across the entire Google ecosystem.
#### Is Video Discovery API the same as Engage?
Yes, they are the same. The Engage SDK is a library that includes support for
the continue watching row. Engage supports more content entity types than video,
which is why the integration is no longer named "Video Discovery".
#### What are the benefits of using Engage?
Answer: Engage makes it easier than ever for viewers to pick up where they left
off on your content, no matter what device they're using. Here's how it works:
- Seamless experience across Google: Start watching on your Google TV, and continue seamlessly on your Android phone, iPhone, or Android tablet. It even works on devices where you haven't installed the app yet!
- Increased engagement and retention: Engage helps bring users back to your app, even on new devices. By letting users resume their favorite shows, you increase the chances they'll keep watching.
- Wider reach: Beyond Google TV, Engage works across other Android media experiences, like Play Collections and other Google media apps.
- Backward compatible: If you're already using the older "[Watch Next](https://developer.android.com/training/tv/discovery/watch-next-add-programs)" feature, no problem! Engage is backward compatible, so your existing integration will still work.
Important Note: All new Continue Watching integrations must use Engage. The
older "Cross Device Play Next" system is being phased out.
#### What surfaces support Engage?
1. Google TV
2. Android TV (on-device only but supports Engage SDK)
3. Google TV Android mobile app
4. Google TV iOS mobile app
5. Play Collections
6. Google entertainment space
7. iOS devices (with REST API integration).
#### Is Engage SDK for Continue Watching?
Yes, the Engage SDK supports content for the continue watching row. It is
required to integrate with Engage.
#### Is Engage available for everyone?
Engage is being rolled out in phases.
- Early Access: We're initially granting access to a select group of partners through an Early Access Program (EAP).
- Expanding Access: We're working hard to make Engage available to all developers soon.
For a smooth and successful launch, we have safeguards in place to manage the
rollout. This involves both an allowlist on the Engage side and a separate check
within the Engage SDK. Whether you are an EAP partner or wants to be onboard
soon, please contact us so that we can set up the access permissions before you
begin with Engage SDK integration.
#### Is there a recommended image size we should provide?
Image requirements have been updated in the [Create Entities](https://developer.android.com/guide/playcore/engage/watch#image-specs)
section.
#### With this new API documentation, will the Continue Watching data pulled by the Google server from the client and will it be reflected in all the devices?
The new API offers significant improvements for content on the continue watching
row, including:
- **Seamless experience across Google TVs:** Users can start watching on one
Google TV and resume on any other Google TV logged in with the same account.
This feature also works with older Android TV versions.
- **Mobile app integration:** Content from Engage is surfaced on the Google TV
mobile app for Android and iOS, allowing users to seamlessly switch between
their TV and mobile devices.
- **Enhanced user retention:** Even on devices without the app installed or
where the user isn't logged in, content in the continue watching row
encourages users to re-engage with your app, boosting retention.
- **Expansion to other platforms:** Engage extends to other Google media
platforms like Android, Play Collections, tablets, and other Google media
apps \& surfaces on Android, maximizing user engagement across devices.
#### What is the limit on the number of entities I can publish to the Continuation cluster?
Each developer partner is limited to a maximum of 5 entities in the Continuation
cluster. This limit is for fair distribution of content on the "continue
watching" row on Google TV, which is a shared space for multiple media
providers.
#### What happens if I try to publish more than 5 entities?
Engage SDK will reject your publish request if it exceeds the 5-entity limit.
You'll need to reduce the number of entities in your request to successfully
publish. You should only include the entities where the users have left off
watching, so in most cases, there will be only a few such entities. When there
are more than 5 such entities, you could choose the more recent ones to publish.
#### Why is there a limit on the number of entities?
The continue watching row on Google TV displays content from various media
providers. Limiting the number of entities per provider so that users see a
diverse selection of content from all their favorite sources, promoting a fair
and balanced user experience.
### Verification App Questions
#### Is it mandatory to test my app with the verification app before submission?
Yes, testing your app with the verification app is essential before submitting
your APK.
While we understand you might be confident in your implementation, the Engage
integration has many intricate components. The verification app acts as a safety
net, catching potential issues early on and saving you valuable time and effort
in the long run.
Think of it as a quick checkup that helps guarantee a smooth launch and a great
user experience.
By identifying and addressing any problems beforehand, you can avoid the
frustration of rejections and resubmissions.
To submit your APK, you'll need to include a screenshot showing that your app
has passed the verification process.
#### What are some common mistakes to watch out for during integration?
The verification app is designed to catch potential issues with your Engage
integration. Here are some common mistakes that developers often encounter:
For all content types (movies, TV episodes, live streams, video clips):
- Missing Links: Make sure you provide valid platform-specific URIs (links) for your content. These links tell the system where to find your content on each platform.
- Missing Titles: Don't forget to include titles for all your content. This helps users identify what they were watching.
- Image Aspect Ratios: Verify all images associated with your content have an aspect ratio close to 16:9. This makes sure your images display correctly on different screens.
For TV Episodes:
- Complete Episode Information: Make sure to include the show title, episode number, and season number. This helps organize episodes and allows users to navigate within a series.
- Accurate Playback Position: Double-check that the last playback position is less than or equal to the total duration of the episode. This makes sure users resume from the correct spot.
For Movies:
- Accurate Playback Position: Similar to TV episodes, verify the last playback position is accurate.
For Live Streaming Videos:
- Broadcaster Information: Include the broadcaster's name for live streams.
For Video Clips:
- Creator Information: Specify the creator of the video clip.
Remember: The verification app will flag these issues, allowing you to fix them
before submitting your app. This saves you time and ensures a smoother
experience for your users.
### Account and Profile Questions
#### My app uses anonymous user logins. Is AccountProfile still required for Engage?
`AccountProfile` is designed for apps that use individual user accounts.
However, we understand that some apps, like yours, may rely on anonymous logins.
Here's how Engage works in this scenario:
- `AccountProfile` is technically required, but you can still integrate Engage even if your app doesn't have a user account system.
- Limited to on-device use: The cross-device capabilities of Engage relies on identifying users across different devices. Since anonymous logins don't provide this, the feature will be limited to the user's current device.
- How to configure: To set this up, you'll need to disable cross-device syncing. This makes sure that continuation entries only appear on the specific device where the content was started.
In summary: While you can integrate Engage with anonymous logins, users will
only be able to resume content on the same device.
#### Can I use AccountProfile with only `accountId` and no `profileId`, even when my app supports both accountId and `profileId`?
AccountProfile requires both `accountId` and `profileId` to function correctly.
Here's why:
- Consistent identification: `accountId` identifies the user, while `profileId` distinguishes between different profiles within that user's account (if applicable). Providing both makes sure that Engage accurately tracks and displays content for each individual profile.
- Preventing errors: Using `accountId` and `profileId` inconsistently across different API calls can lead to unexpected behavior and errors. For example, if you include both when adding content to Engage but only use `accountId` when deleting content, the system may not be able to correctly identify and remove the intended items.
#### Is `profileId` required for Engage?
- `accountId` is required. This identifies the user across devices.
- `profileId` is crucial for a good user experience. While technically optional, `profileId` is strongly recommended if your service supports multiple profiles (like many streaming services do). Why is it so important? Because without `profileId`, the continue watching row may show content from other profiles on the same account. This can lead to a confusing and frustrating experience for your users.
- In short: Providing `profileId` makes sure that content provided to the continue watching row accurately reflects each individual's viewing history. Unless your app doesn't support the concept of profile within an account, you should provide it.
#### How does Google use the `profileId` on their side?
If the service offers different profiles to watch content, `accountId` and
`profileId` would be used to associate the content watched on the device to the
signed-in Google Account on the device. Google would record the ContinueWatching
data against the combination of `accountId` and `profileId`. Any Google device
that has that same Google Account logged in, would get the latest updated data
from the same associated `accountId` and `profileId`, in its ContinueWatching
row.
#### Is account linking required to implement Engage?
Account Linking is not needed. It is being deprioritized and all related use
cases will be covered by the new Device Entitlements API.
### Sync Across Devices Questions
#### What does "sync across devices" mean when users give consent?
With the user's "sync across device" consent, the content they're watching will
be saved to Google TV servers, letting them seamlessly pick up where they left
off on any signed-in device. Without consent, their watch history remains local
to the current device.
#### Can we set "sync across devices" to false?
The `setUserConsentToSyncAcrossDevices` flag controls whether a user's
ContinuationCluster data is synchronized across their devices (TV, phone,
tablet, etc.). If this flag is set to false, then continue watching content is
only surfaced on same device.
To get the most out of our cross-device feature, we strongly advise your app to
obtain user consent and set SyncAcrossDevices to true.
#### How is user consent for sharing watch history obtained on non-Android
devices? What data points are shared to 3P servers from non-Android devices?
The consent is collected at the user level (profile or account level). Once
consent is obtained, the continue watching payloads based on engagement can be
sent anywhere so Google can reflect the users' ubiquity resumption state across
all entities that they have partial or next engagement with, on any device
(without having to re-ask consent on every device or platform). Partners will
send the users latest continue watching state (as per spec) associated with
profile ID (that was deposited on android).
### REST API Questions
#### Is there documentation on the REST API?
The ETA for REST API is March 2025, this is documented in Engage Developer Docs.
### Legacy Watch Next Questions
#### Is Engage replacing the Watch Next API?
Engage will be backward compatible on all Android TV devices that support the
Watch Next API. To integrate on Google TV and other surfaces that support
Engage, developers should use the Engage SDK.
### Testing and Integration Questions
#### What is the difference between LastPlayBackPositionTimeMillis and duration?
LastPlayBackPositionTimeMillis should reflect the playback duration in
milliseconds where the user stopped watching (e.g., 605000 ms for 10 minutes and
5 seconds). It should never be greater than the entity's total duration.
Whereas, **LastEngagementTime** is the timestamp when the user last engaged with
the content.
#### What are the test cases we should perform?
The following are test cases for Google TV that our QA performs. Similar test
cases can be performed on other surfaces as well.
1. Watch a video, which is longer than 20 minutes for about 5 minutes. Exit app. The video card should be displayed in the continue watching row. Note: We only display 5 cards per 3p app in CW
2. Selecting the newly appeared card in the continue watching row should continue playing the video from the right point in the video.Note: Any New or old content should resume playback from where it was left off last
3. Changing accounts on the GTV device should change the cards on the continue watching row. Only videos from the current account should show up. Sorted in recent order. 3p app profile CW will be intermixed. Note: CW for GoogleAccount2 will show 3P contents that GoogleAccount2 was engaged watching
4. Exit the app with BACK button \> Verify card is displayed in the "Continue watching" row
5. Hide the video in the continue watching row, it shouldn't show again Test if hidden content stays hidden beyond 24 hours and even after the app opens after 24 hrs. Confirm hiding one item does not hide multiple items.
6. Content availability in the continue watching row with full metadata: Card image, App name, title, season episode # for TV contents
7. Check Progress displays in the progress bar
8. User watched the content until ending credits - content does not display in the continue watching row
9. Confirm no unwatched items show up in the continue watching row
10. Confirm that the CW items are arranged chronologically based on when watch activity happened and not when the app was last opened or last day
11. Confirm that episode and season details on CW card match what was watched on episodic content
12. Confirm completed (items at credits or beyond) items don't show up in the continue watching row
13. Turn off the device halfway through watching the episode/movie/show. "Turn off the device halfway through watching the episode/movie/show. Verify on turning on the device and on other TV, CW displays the right card , at the right position and progress bar"
14. Turn off the device after completely watching episode 1, verify
15. episode 1 drops and doesn't reappear in continue watching row \[on second device and on turning on the test device\]
1. episode 2 (if available), should appear in continue watching row \[on second device and on turning on the test device\]
16. First scenario: TV1: GoogleAccount: mom, 3p account / profile: account 1 / profile_1. Watch content and verify CW data displays contents watched by 3P account_1/profile_1
17. TV2: GoogleAccount: mom. Verify CW data from the first scenario. Now login
to the 3p app as a different account. 3p account / profile: account_2 /
profile_2. Watch content and verify CW data displays contents watched by 3p
account_2/profile_2
18. GoogleAccount: mom. New device case /3P app not installed. On a new
device(FDR the device), Verify CW displays data from the last used 3P app
that was used by the GoogleAccount. Note: CW row shouldn't show 3P contents
if the GAIA is not yet associated with a 3P profile on other device
1. GoogleAccount: mom. New device case /3P app installed but not logged in. On a new device(FDR the device), Verify CW displays data from the last used 3P app that was used by the GoogleAccount.
19.
> [!NOTE]
> **Note:** When the app is installed and logged in, the CW state would reflect the active 3P user logged into the 3P app.
1. Note: the continue watching row shouldn't show 3P contents if the GoogleAccount is not yet associated with a 3P profile
#### We are not seeing continuation content showing up on Google TV iOS app. What happened?
You will need to send iOS deeplinks for content to appear in the continue
watching row on iOS devices.
#### How often should I update content information for the continue watching row? Should I update it frequently, like every 15 seconds?
No, frequent updates are not recommended. Here's why:
- Performance Impact: Continuously sending updates puts unnecessary strain on our servers, potentially slowing down the system for everyone.
- Unnecessary Data: While a user is actively watching, their playback position changes constantly. Sending updates every few seconds creates a lot of redundant data that isn't helpful for resuming playback.
When to update content information for the continue watching row:
Focus on capturing meaningful changes in the user's viewing progress. Here are
the key scenarios:
- Playback Paused or Stopped: When a user pauses or stops watching, send an update to store their current position.
- App Closed or Backgrounded: If a user exits the app or switches to another app while watching a video, send an update to save their progress.
- When user removes an item from their continue watching row within app
How to efficiently update:
Instead of timed updates, utilize events within your video player or app
lifecycle to trigger updates. For example:
- `onPause`, `onStop`: When the video playback pauses or stops.
- `onAppClose`, `onAppBackgrounded`: When the app closes or moves to the background.
By following these guidelines, you'll ensure efficient use of resources while
still providing a seamless experience in the continue watching row for your
users.
> [!NOTE]
> **Note:** Please contact [`engage-developers@google.com`](mailto:engage-developers@google.com) if you have any questions that are not covered here.

1132
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/food.md Normal file
View File

File diff suppressed because it is too large Load Diff

1038
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/healthandfitness.md Normal file
View File

File diff suppressed because it is too large Load Diff

1033
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/listen.md Normal file
View File

File diff suppressed because it is too large Load Diff

1284
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/otherverticals.md Normal file
View File

File diff suppressed because it is too large Load Diff

893
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/read.md Normal file
View File

@@ -0,0 +1,893 @@
> [!IMPORTANT]
> **Important:** Engage SDK has superseded Media Home, which is now deprecated. If you have an existing Media Home integration, follow the instructions in these guides to migrate your content to Engage SDK, which allows your content to be published to more devices and form factors. Please contact [`engage-developers@google.com`](mailto:engage-developers@google.com) if you have any questions.
Boost app engagement by reaching your users where they are. Integrate Engage SDK
to deliver personalized recommendations and continuation content directly to
users across multiple on-device surfaces, like
**[Collections](https://android-developers.googleblog.com/2024/07/introducing-collections-powered-by-engage-sdk.html)** , **[Entertainment
Space](https://blog.google/products/android/entertainment-space/)** , and the Play Store. The integration adds
less than 50 KB (compressed) to the average APK and takes most apps about a
week of developer time. Learn more at our **[business
site](http://play.google.com/console/about/programs/EngageSDK)**.
This guide contains instructions for developer partners to deliver reading
content (eBooks, Audiobooks, Comics/Manga) to Engage content surfaces.
## Integration detail
### Terminology
This integration includes the following three cluster types: **Recommendation** ,
**Continuation** , and **Featured**.
- **Recommendation** clusters show personalized suggestions for content to read
from an individual developer partner.
Your recommendations take the following structure:
- **Recommendation Cluster:** A UI view that contains a group of
recommendations from a single developer partner.
![](https://developer.android.com/static/images/guide/playcore/engage/read-term-1.png) **Figure 1.** Entertainment Space UI showing a Recommendation Cluster from a single partner.
- **Entity:** An object representing a single item in a cluster. An entity
can be an ebook, an audio book, a book series, and more. See the [Provide
entity data](https://developer.android.com/guide/playcore/engage/read#provide-entity-data) section for a list of supported entity
types.
![](https://developer.android.com/static/images/guide/playcore/engage/read-term-2.png) **Figure 2.** Entertainment Space UI showing a single Entity within a single partner's Recommendation Cluster.
- The **Continuation** cluster shows unfinished books from multiple developer
partners in a single UI grouping. Each developer partner will be allowed to
broadcast a maximum of 10 entities in the Continuation cluster.
![](https://developer.android.com/static/images/guide/playcore/engage/read-term-3.png) **Figure 3.** Entertainment Space UI showing a Continuation cluster with unfinished recommendations from multiple partners (only one recommendation is currently visible).
- The **Featured** cluster showcases a selection of items from multiple
developer partners in a single UI grouping. There will be a single Featured
cluster, which is surfaced near the top of the UI with a priority placement
above all Recommendation clusters. Each developer partner will be allowed to
broadcast up to 10 entities in the Featured cluster.
![](https://developer.android.com/static/images/guide/playcore/engage/read-term-4.png) **Figure 4.** Entertainment Space UI showing a Featured cluster with recommendations from multiple partners (only one recommendation is currently visible).
### Pre-work
Minimum API level: 19
Add the `com.google.android.engage:engage-core` library to your app:
dependencies {
// Make sure you also include that repository in your project's build.gradle file.
implementation 'com.google.android.engage:engage-core:1.6.0'
}
### Summary
The design is based on an implementation of a [bound
service](https://developer.android.com/guide/components/bound-services).
The data a client can publish is subject to the following limits for different
cluster types:
| Cluster type | Cluster limits | Maximum entity limits in a cluster |
|---|---|---|
| Recommendation Cluster(s) | At most 7 | At most 50 |
| Continuation Cluster | At most 1 | At most 20 |
| Featured Cluster | At most 1 | At most 20 |
### Step 1: Provide entity data
The SDK has defined different entities to represent each item type. We support
the following entities for the Read category:
1. `EbookEntity`
2. `AudiobookEntity`
3. `BookSeriesEntity`
The charts below outline available attributes and requirements for each type.
#### `EbookEntity`
The `EbookEntity` object represents an ebook (for example, the ebook of
*Becoming* by Michelle Obama).
| Attribute | Requirement | Notes |
|---|---|---|
| Name | **Required** | |
| Poster images | **Required** | At least one image must be provided. See [Image Specifications](https://developer.android.com/guide/playcore/engage/read#image-specs) for guidance. |
| Author | **Required** | At least one author name must be provided. |
| Action link uri | **Required** | The deep link to the provider app for the ebook. Note: You can use deep links for attribution. [Refer to this FAQ](https://developer.android.com/guide/playcore/engage/faq#deeplinks-attribution) |
| Publish date | Optional | In epoch milliseconds if provided. |
| Description | Optional | Must be within 200 characters if provided. |
| Price | Optional | Free text |
| Page count | Optional | Must be a positive integer if provided. |
| Genre | Optional | List of genres associated with the book. |
| Series name | Optional | Name of the series that the ebook belongs to (for example, *Harry Potter*). |
| Series unit index | Optional | The index of the ebook in the series, where 1 is the first ebook in the series. For example, if *Harry Potter and the Prisoner of Azkaban* is the 3rd book in the series, this should be set to 3. |
| Continue book type | Optional | TYPE_CONTINUE - Resume on a unfinished book. TYPE_NEXT - Continue on a new one of a series. TYPE_NEW - Newly released. |
| Last Engagement Time | Conditionally required | Must be provided when the item is in the Continuation cluster. \*Newly\* acquired ebooks can be a part of the continue reading cluster. In epoch milliseconds. |
| Progress Percentage Complete | Conditionally required | Must be provided when the item is in the Continuation cluster. Value must be greater than 0 and less than 100. |
| **DisplayTimeWindow - Set a time window for a content to be shown on the surface** |||
| Start Timestamp | Optional | The epoch timestamp after which the content should be shown on the surface. If not set, content is eligible to be shown on the surface. In epoch milliseconds. |
| End Timestamp | Optional | The epoch timestamp after which the content is no longer shown on the surface. If not set, content is eligible to be shown on the surface. In epoch milliseconds. |
#### `AudiobookEntity`
The `AudiobookEntity` object represents an audiobook (for example, the audiobook
of *Becoming* by Michelle Obama).
| Attribute | Requirement | Notes |
|---|---|---|
| Name | **Required** | |
| Poster images | **Required** | At least one image must be provided. See [Image Specifications](https://developer.android.com/guide/playcore/engage/read#image-specs) for guidance. |
| Author | **Required** | At least one author name must be provided. |
| Action link uri | **Required** | The deep link to the provider app for the audiobook. Note: You can use deep links for attribution. [Refer to this FAQ](https://developer.android.com/guide/playcore/engage/faq#deeplinks-attribution) |
| Narrator | Optional | At least one narrator's name must be provided. |
| Publish date | Optional | In epoch milliseconds if provided. |
| Description | Optional | Must be within 200 characters if provided. |
| Price | Optional | Free text |
| Duration | Optional | Must be a positive value if provided. |
| Genre | Optional | List of genres associated with the book. |
| Series name | Optional | Name of the series that the audiobook belongs to (for example, *Harry Potter*. |
| Series unit index | Optional | The index of the audiobook in the series, where 1 is the first audiobook in the series. For example, if *Harry Potter and the Prisoner of Azkaban* is the 3rd book in the series, this should be set to 3. |
| Continue book type | Optional | TYPE_CONTINUE - Resume on a unfinished book. TYPE_NEXT - Continue on a new one of a series. TYPE_NEW - Newly released. |
| Last Engagement Time | Conditionally required | Must be provided when the item is in the Continuation cluster. In epoch milliseconds. |
| Progress Percentage Complete | Conditionally required | Must be provided when the item is in the Continuation cluster. \*Newly\* acquired audiobooks can be a part of the continue reading cluster. Value must be greater than 0 and less than 100. |
| **DisplayTimeWindow - Set a time window for a content to be shown on the surface** |||
| Start Timestamp | Optional | The epoch timestamp after which the content should be shown on the surface. If not set, content is eligible to be shown on the surface. In epoch milliseconds. |
| End Timestamp | Optional | The epoch timestamp after which the content is no longer shown on the surface. If not set, content is eligible to be shown on the surface. In epoch milliseconds. |
#### `BookSeriesEntity`
The `BookSeriesEntity` object represents a book series (for example, the *Harry
Potter* book series, which has 7 books).
| Attribute | Requirement | Notes |
|---|---|---|
| Name | **Required** | |
| Poster images | **Required** | At least one image must be provided. See [Image Specifications](https://developer.android.com/guide/playcore/engage/read#image-specs) for guidance. |
| Author | **Required** | At least one author name must be present. |
| Action link uri | **Required** | The deep link to the provider app for the audiobook or ebook. Note: You can use deep links for attribution. [Refer to this FAQ](https://developer.android.com/guide/playcore/engage/faq#deeplinks-attribution) |
| Book count | **Required** | Number of books in the series. |
| Description | Optional | Must be within 200 characters if provided. |
| Genre | Optional | List of genres associated with the book. |
| Continue book type | Optional | TYPE_CONTINUE - Resume on a unfinished book. TYPE_NEXT - Continue on a new one of a series. TYPE_NEW - Newly released. |
| Last Engagement Time | Conditionally required | Must be provided when the item is in the Continuation cluster. In epoch milliseconds. |
| Progress Percentage Complete | Conditionally required | Must be provided when the item is in the Continuation cluster. \*Newly\* acquired book series can be a part of the continue reading cluster. Value must be greater than 0 and less than 100. |
| **DisplayTimeWindow - Set a time window for a content to be shown on the surface** |||
| Start Timestamp | Optional | The epoch timestamp after which the content should be shown on the surface. If not set, content is eligible to be shown on the surface. In epoch milliseconds. |
| End Timestamp | Optional | The epoch timestamp after which the content is no longer shown on the surface. If not set, content is eligible to be shown on the surface. In epoch milliseconds. |
#### Image specifications
Required specifications for image assets are listed below:
| Aspect ratio | Supported cluster(s) | Minimum pixels | Recommended pixels |
|---|---|---|---|
| Square (1x1) | All clusters | 300x300 | 1200x1200 |
| Landscape (1.91x1) | Featured and continuation | 600x314 | 1200x628 |
| Portrait (4x5) | Recommendation | 480x600 | 960x1200 |
*File formats*
PNG, JPG, static GIF, WebP
*Maximum file size*
5120 KB
*Additional recommendations*
- **Image safe area:** Put your important content in the center 80% of the image.
#### Example
AudiobookEntity audiobookEntity =
new AudiobookEntity.Builder()
.setName("Becoming")
.addPosterImage(
new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.addAuthor("Michelle Obama")
.addNarrator("Michelle Obama")
.setActionLinkUri(Uri.parse("https://play.google/audiobooks/1"))
.setDurationMillis(16335L)
.setPublishDateEpochMillis(1633032895L)
.setDescription("An intimate, powerful, and inspiring memoir")
.setPrice("$16.95")
.addGenre("biography")
.build();
### Step 2: Provide Cluster data
It's recommended to have the content publish job executed in the background
(for example, using [WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager))
and scheduled on a regular basis or on an event basis (for example, every time
the user opens the app or when the user just added something to their cart).
`AppEngagePublishClient` is responsible for publishing clusters. Following
APIs are available in the client:
- `isServiceAvailable`
- `publishRecommendationClusters`
- `publishFeaturedCluster`
- `publishContinuationCluster`
- `publishUserAccountManagementRequest`
- `updatePublishStatus`
- `deleteRecommendationsClusters`
- `deleteFeaturedCluster`
- `deleteContinuationCluster`
- `deleteUserManagementCluster`
- `deleteClusters`
#### `isServiceAvailable`
This API is used to check if the service is available for integration and
whether the content can be presented on the device.
##### For Engage SDK v1.6.0 and higher (Recommended)
You can check the service availability for every cluster type that you intend to
publish. The `isServiceAvailable` API accepts a request object,
`ServiceAvailabilityRequest`, which contains the cluster types for which service
availability needs to be checked. You can find the `ClusterType` enum values
required for `ServiceAvailabilityRequest` from the following table.
| Cluster Type | Cluster Type Constant | Integer Value |
|---|---|---|
| Unknown | `TYPE_UNKNOWN` | 0 |
| Recommendation Cluster | `TYPE_RECOMMENDATION` | 1 |
| Featured Cluster | `TYPE_FEATURED` | 2 |
| Continuation Cluster | `TYPE_CONTINUATION` | 3 |
| User Management Cluster | `TYPE_ENGAGEMENT` | 8 |
| Subscription Cluster | `TYPE_SUBSCRIPTION` | 12 |
### Kotlin
val request = ServiceAvailabilityRequest.Builder()
.addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
.addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
.build()
client.isServiceAvailable(request).addOnCompleteListener { task ->
if (task.isSuccessful) {
val availabilityMap = task.result
if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
// Proceed with publishing continuation content
}
if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
// Proceed with publishing recommendation content
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
### Java
ServiceAvailabilityRequest request =
new ServiceAvailabilityRequest.Builder()
.addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
.addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
.build();
client.isServiceAvailable(request).addOnCompleteListener(task -> {
if (task.isSuccessful()) {
Map<Integer, Boolean> availabilityMap = task.getResult();
if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
// Proceed with publishing continuation content
}
if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
// Proceed with publishing recommendation content
}
} else {
// The IPC call itself fails, proceed with error handling logic here such as retry.
}
});
###### Conditional Service Availability Feature
Some integrated apps request a special configuration that enables and disables
the Engage service intermittently in order to reduce their serving cost. This
intermittent content ingestion strategy, although possible, negatively affects
the user and the product -- stale content will not be presented and some surfaces
will not be served at all.
Starting with v1.6.0, the Engage SDK allows checking availability for specific
cluster types. This provides more flexibility so that if the intermittent
content strategy was adopted by a given application, some cluster types can
follow that intermittent strategy while other cluster types are always enabled
(i.e. continuation clusters).
If the Engage service should not be 'continuously' enabled on all supported
devices for whatever reason, and is configured for intermittent ingestion for
any set of devices, all continuation cluster publications (e.g. Continue
Reading) will be still enabled by default
configuration, and the rest of the cluster types will be enabled and disabled
intermittently. If intermittent ingestion applies to you but this default
configuration is not suitable for your needs, please contact
engage-developers@google.com.
##### For SDK versions prior to v1.6.0 (Deprecated)
### Kotlin
client.isServiceAvailable.addOnCompleteListener { task ->
if (task.isSuccessful) {
// Handle IPC call success
if(task.result) {
// Service is available on the device, proceed with content publish
// calls.
} else {
// Service is not available, no further action is needed.
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
### Java
client.isServiceAvailable().addOnCompleteListener(task - > {
if (task.isSuccessful()) {
// Handle success
if(task.getResult()) {
// Service is available on the device, proceed with content publish
// calls.
} else {
// Service is not available, no further action is needed.
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
});
> [!NOTE]
> **Note:** We highly recommend keeping a periodic job running to check if the service becomes available at a later point in time. The availability of the service may change with Android version upgrades, app upgrades, installs, and uninstalls. By ensuring periodic job checks at a certain time interval, data can be published once the service becomes available.
#### `publishRecommendationClusters`
This API is used to publish a list of `RecommendationCluster` objects.
> [!IMPORTANT]
> **Important:** The publish APIs are upsert APIs; it replaces the existing content. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.
### Kotlin
client.publishRecommendationClusters(
PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(
RecommendationCluster.Builder()
.addEntity(entity1)
.addEntity(entity2)
.setTitle("Reconnect with yourself")
.build())
.build())
### Java
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(
new RecommendationCluster.Builder()
.addEntity(entity1)
.addEntity(entity2)
.setTitle("Reconnect with yourself")
.build())
.build());
When the service receives the request, the following actions take place within
one transaction:
- Existing `RecommendationCluster` data from the developer partner is removed.
- Data from the request is parsed and stored in the updated Recommendation Cluster.
In case of an error, the entire request is rejected and the existing state is
maintained.
#### `publishFeaturedCluster`
This API is used to publish a list of `FeaturedCluster` objects.
> [!IMPORTANT]
> **Important:** The publish APIs are upsert APIs; it replaces the existing content. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.
### Kotlin
client.publishFeaturedCluster(
PublishFeaturedClusterRequest.Builder()
.setFeaturedCluster(
FeaturedCluster.Builder()
...
.build())
.build())
### Java
client.publishFeaturedCluster(
new PublishFeaturedClusterRequest.Builder()
.setFeaturedCluster(
new FeaturedCluster.Builder()
...
.build())
.build());
When the service receives the request, the following actions take place within
one transaction:
- Existing `FeaturedCluster` data from the developer partner is removed.
- Data from the request is parsed and stored in the updated Featured Cluster.
In case of an error, the entire request is rejected and the existing state is
maintained.
#### `publishContinuationCluster`
This API is used to publish a `ContinuationCluster` object.
> [!IMPORTANT]
> **Important:** The publish APIs are upsert APIs; it replaces the existing content. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.
### Kotlin
client.publishContinuationCluster(
PublishContinuationClusterRequest.Builder()
.setContinuationCluster(
ContinuationCluster.Builder()
.addEntity(book_entity1)
.addEntity(book_entity2)
.build())
.build())
### Java
client.publishContinuationCluster(
PublishContinuationClusterRequest.Builder()
.setContinuationCluster(
ContinuationCluster.Builder()
.addEntity(book_entity1)
.addEntity(book_entity2)
.build())
.build())
When the service receives the request, the following actions take place within
one transaction:
- Existing `ContinuationCluster` data from the developer partner is removed.
- Data from the request is parsed and stored in the updated Continuation Cluster.
In case of an error, the entire request is rejected and the existing state is
maintained.
#### `publishUserAccountManagementRequest`
This API is used to publish a Sign In card . The signin action directs users to
the app's sign in page so that the app can publish content (or provide more
personalized content)
The following metadata is part of the Sign In Card -
| Attribute | Requirement | Description |
|---|---|---|
| Action Uri | Required | Deeplink to Action (i.e. navigates to app sign in page) |
| Image | Optional - If not provided, Title must be provided | Image Shown on the Card 16x9 aspect ratio images with a resolution of 1264x712 |
| Title | Optional - If not provided, Image must be provided | Title on the Card |
| Action Text | Optional | Text Shown on the CTA (i.e. Sign in) |
| Subtitle | Optional | Optional Subtitle on the Card |
> [!IMPORTANT]
> **Important:** The publish APIs are upsert APIs; it replaces the existing content. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.
### Kotlin
var SIGN_IN_CARD_ENTITY =
SignInCardEntity.Builder()
.addPosterImage(
Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(500)
.setImageWidthInPixel(500)
.build())
.setActionText("Sign In")
.setActionUri(Uri.parse("http://xx.com/signin"))
.build()
client.publishUserAccountManagementRequest(
PublishUserAccountManagementRequest.Builder()
.setSignInCardEntity(SIGN_IN_CARD_ENTITY)
.build());
### Java
SignInCardEntity SIGN_IN_CARD_ENTITY =
new SignInCardEntity.Builder()
.addPosterImage(
new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(500)
.setImageWidthInPixel(500)
.build())
.setActionText("Sign In")
.setActionUri(Uri.parse("http://xx.com/signin"))
.build();
client.publishUserAccountManagementRequest(
new PublishUserAccountManagementRequest.Builder()
.setSignInCardEntity(SIGN_IN_CARD_ENTITY)
.build());
When the service receives the request, the following actions take place within
one transaction:
- Existing `UserAccountManagementCluster` data from the developer partner is removed.
- Data from the request is parsed and stored in the updated UserAccountManagementCluster Cluster.
In case of an error, the entire request is rejected and the existing state is
maintained.
#### `updatePublishStatus`
If for any internal business reason, none of the clusters is published,
we **strongly recommend** updating the publish status using the
**updatePublishStatus** API.
This is important because :
- Providing the status in all scenarios, even when the content is published (STATUS == PUBLISHED), is critical to populate dashboards that use this explicit status to convey the health and other metrics of your integration.
- If no content is published but the integration status isn't broken (STATUS == NOT_PUBLISHED), Google can avoid triggering alerts in the app health dashboards. It confirms that content is not published due to an **expected** situation from the provider's standpoint.
- It helps developers provide insights into when the data is published versus not.
- Google may use the status codes to nudge the user to do certain actions in the app so they can see the app content or overcome it.
The list of eligible publish status codes are :
// Content is published
AppEngagePublishStatusCode.PUBLISHED,
// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,
// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,
// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,
// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,
// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,
// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,
// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,
// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER
If the content is not published due to a user not logged in,
Google would recommend publishing the Sign In Card.
If for any reason providers are not able to publish the Sign In Card
then we recommend calling the **updatePublishStatus** API
with the status code **NOT_PUBLISHED_REQUIRES_SIGN_IN**
### Kotlin
client.updatePublishStatus(
PublishStatusRequest.Builder()
.setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
.build())
### Java
client.updatePublishStatus(
new PublishStatusRequest.Builder()
.setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
.build());
#### `deleteRecommendationClusters`
This API is used to delete the content of Recommendation Clusters.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteRecommendationClusters()
### Java
client.deleteRecommendationClusters();
When the service receives the request, it removes the existing data from the
Recommendation Clusters. In case of an error, the entire request is rejected
and the existing state is maintained.
> [!NOTE]
> **Note:** This api is available from version 1.1.0 onwards.
#### `deleteFeaturedCluster`
This API is used to delete the content of Featured Cluster.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteFeaturedCluster()
### Java
client.deleteFeaturedCluster();
When the service receives the request, it removes the existing data from the
Featured Cluster. In case of an error, the entire request is rejected
and the existing state is maintained.
> [!NOTE]
> **Note:** This api is available from version 1.1.0 onwards.
#### `deleteContinuationCluster`
This API is used to delete the content of Continuation Cluster.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteContinuationCluster()
### Java
client.deleteContinuationCluster();
When the service receives the request, it removes the existing data from the
Continuation Cluster. In case of an error, the entire request is rejected
and the existing state is maintained.
> [!NOTE]
> **Note:** This api is available from version 1.1.0 onwards.
#### `deleteUserManagementCluster`
This API is used to delete the content of UserAccountManagement Cluster.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteUserManagementCluster()
### Java
client.deleteUserManagementCluster();
When the service receives the request, it removes the existing data from the
UserAccountManagement Cluster. In case of an error, the entire request is
rejected and the existing state is maintained.
> [!NOTE]
> **Note:** This api is available from version 1.1.0 onwards.
#### `deleteClusters`
This API is used to delete the content of a given cluster type.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteClusters(
DeleteClustersRequest.Builder()
.addClusterType(ClusterType.TYPE_FEATURED)
.addClusterType(ClusterType.TYPE_RECOMMENDATION)
...
.build())
### Java
client.deleteClusters(
new DeleteClustersRequest.Builder()
.addClusterType(ClusterType.TYPE_FEATURED)
.addClusterType(ClusterType.TYPE_RECOMMENDATION)
...
.build());
When the service receives the request, it removes the existing data from all
clusters matching the specified cluster types. Clients can choose to pass one or
many cluster types. In case of an error, the entire request is rejected and the
existing state is maintained.
#### Error handling
It is highly recommended to listen to the task result from the publish APIs such
that a follow-up action can be taken to recover and resubmit an successful task.
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(...)
.build())
.addOnCompleteListener(
task -> {
if (task.isSuccessful()) {
// do something
} else {
Exception exception = task.getException();
if (exception instanceof AppEngageException) {
@AppEngageErrorCode
int errorCode = ((AppEngageException) exception).getErrorCode();
if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
// do something
}
}
}
});
The error is returned as an `AppEngageException` with the cause included as an
error code.
| Error code | Error name | Note |
|---|---|---|
| `1` | `SERVICE_NOT_FOUND` | The service is not available on the given device. |
| `2` | `SERVICE_NOT_AVAILABLE` | The service is available on the given device, but it is not available at the time of the call (for example, it is explicitly disabled). |
| `3` | `SERVICE_CALL_EXECUTION_FAILURE` | The task execution failed due to threading issues. In this case, it can be retried. |
| `4` | `SERVICE_CALL_PERMISSION_DENIED` | The caller is not allowed to make the service call. |
| `5` | `SERVICE_CALL_INVALID_ARGUMENT` | The request contains invalid data (for example, more than the allowed number of clusters). |
| `6` | `SERVICE_CALL_INTERNAL` | There is an error on the service side. |
| `7` | `SERVICE_CALL_RESOURCE_EXHAUSTED` | The service call is made too frequently. |
### Step 3: Handle broadcast intents
In addition to making publish content API calls through a job, it is also
required to set up a
[`BroadcastReceiver`](https://developer.android.com/reference/android/content/BroadcastReceiver) to receive
the request for a content publish.
The goal of broadcast intents is mainly for app reactivation and forcing data
sync. Broadcast intents are not designed to be sent very frequently. It is only
triggered when the Engage Service determines the content might be stale (for
example, a week old). That way, there is more confidence that the user can have
a fresh content experience, even if the application has not been executed for a
long period of 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.
### Kotlin
class AppEngageBroadcastReceiver : BroadcastReceiver(){
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}
fun registerBroadcastReceivers(context: Context){
var context = context
context = context.applicationContext
// Register Recommendation Cluster Publish Intent
context.registerReceiver(AppEngageBroadcastReceiver(),
IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null)
// Register Featured Cluster Publish Intent
context.registerReceiver(AppEngageBroadcastReceiver(),
IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null)
// Register Continuation Cluster Publish Intent
context.registerReceiver(AppEngageBroadcastReceiver(),
IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null)
}
### Java
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}
public static void registerBroadcastReceivers(Context context) {
context = context.getApplicationContext();
// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null);
// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null);
// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null);
}
- 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.
<application>
<receiver
android:name=".AppEngageBroadcastReceiver"
android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
android:exported="true"
android:enabled="true">
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
</intent-filter>
</receiver>
</application>
The following [intents](https://developer.android.com/reference/android/content/Intent) will be sent by the
service:
- `com.google.android.engage.action.PUBLISH_RECOMMENDATION` It is recommended to start a `publishRecommendationClusters` call when receiving this intent.
- `com.google.android.engage.action.PUBLISH_FEATURED` It is recommended to start a `publishFeaturedCluster` call when receiving this intent.
- com.google.android.engage.action.PUBLISH_CONTINUATION`It is recommended to start a`publishContinuationCluster\` call when receiving this intent.
## Integration workflow
For a step-by-step guide on verifying your integration after it is complete, see
[Engage developer integration workflow](https://developer.android.com/guide/playcore/engage/workflow).
## FAQs
See [Engage SDK Frequently Asked Questions](https://developer.android.com/guide/playcore/engage/faq) for
FAQs.
## Contact
Contact [`engage-developers@google.com`](mailto:engage-developers@google.com) if there are any questions during
the integration process. Our team will reply as soon as possible.
## Next steps
After completing this integration, your next steps are as follows:
- Send an email to [`engage-developers@google.com`](mailto:engage-developers@google.com) and attach your integrated APK that is ready for testing by Google.
- Google will perform a verification and review internally to make sure the integration works as expected. If changes are needed, Google will contact you with any necessary details.
- When testing is complete and no changes are needed, Google will contact you to notify you that you can start publishing the updated and integrated APK to the Play Store.
- After Google has confirmed that your updated APK has been published to the Play Store, your **Recommendation** , **Featured** , and **Continuation** clusters will be published and visible to users.

1207
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/shopping.md Normal file
View File

File diff suppressed because it is too large Load Diff

702
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/social.md Normal file
View File

@@ -0,0 +1,702 @@
Boost app engagement by reaching your users where they are. Integrate Engage SDK
to deliver personalized recommendations and continuation content directly to
users across multiple on-device surfaces, like
**[Collections](https://android-developers.googleblog.com/2024/07/introducing-collections-powered-by-engage-sdk.html)** , **[Entertainment
Space](https://blog.google/products/android/entertainment-space/)** , and the Play Store. The integration adds
less than 50 KB (compressed) to the average APK and takes most apps about a
week of developer time. Learn more at our **[business
site](http://play.google.com/console/about/programs/EngageSDK)**.
This guide contains instructions for developer partners to deliver social media
content to Engage content surfaces.
## Integration detail
The following section captures the integration detail.
### Terminology
***Recommendation*** clusters show personalized suggestions from an individual
developer partner.
Your recommendations take the following structure:
**Recommendation Cluster**: UI view that contains a group of recommendations
from the same developer partner.
Each Recommendation Cluster consists of one of the following two types of
entities :
- PortraitMediaEntity
- SocialPostEntity
**PortraitMediaEntity** must contain 1 portrait image for the post. Profile and
Interaction related metadata are optional.
- Post
- Image in portrait mode and Timestamp, or
- Image in portrait mode + text content and Timestamp
- Profile
- Avatar, Name or Handle, Additional image
- Interactions
- Count and label only, or
- Count and visual (icon)
**SocialPostEntity** contains profile, post and interaction related metadata.
- Profile
- Avatar, Name or Handle, additional text, additional image
- Post
- Text and Timestamp, or
- Rich media (image or rich URL) and Timestamp, or
- Text and rich media (image or rich URL) and Timestamp, or
- Video preview (thumbnail and duration) and Timestamp
- Interactions
- Count \& label only, or
- Count \& visual (icon)
### Pre-work
Minimum API level: 19
Add the `com.google.android.engage:engage-core` library to your app:
dependencies {
// Make sure you also include that repository in your project's build.gradle file.
implementation 'com.google.android.engage:engage-core:1.6.0'
}
### Summary
The design is based on an implementation of a [bound
service](https://developer.android.com/guide/components/bound-services).
The data a client can publish is subject to the following limits for different
cluster types:
| Cluster type | Cluster limits | Minimum entity limits in a cluster | Maximum entity limits in a cluster |
|---|---|---|---|
| Recommendation Cluster(s) | At most 7 | At least 1 (`PortraitMediaEntity`, or `SocialPostEntity`) | At most 50 (`PortraitMediaEntity`, or `SocialPostEntity`) |
### Step 1: Provide entity data
The SDK has defined different entities to represent each item type. The SDK
supports the following entities for the Social category:
1. `PortraitMediaEntity`
2. `SocialPostEntity`
The charts below outline available attributes and requirements for each type.
#### `PortraitMediaEntity`
| Attribute | Requirement | Description | Format |
|---|---|---|---|
| Action URI | **Required** for all surfaces other than Google TV | Deep Link to the entity in the provider app. Note: You can use deep links for attribution. [Refer to this FAQ](https://developer.android.com/guide/playcore/engage/faq#deeplinks-attribution) | URI |
| PlatformSpecificPlayback | **Required** for Google TV surface | Deep Link to the entity in the provider app for platforms like Google TV and Mobile. | List of PlatformSpecificPlayback objects |
| Recommendation Reason | Optional | The justification for recommending the content to the user. | RecommendationReason object |
| Comments Summary | Optional | Summary of comments for the post. | String |
| **Post related metadata (Required)** ||||
| Image(s) | Required | Image(s) should be in **portrait aspect ratio.** The UI may show only 1 image when multiple images are provided. However, the UI may provide visual indication that there are more images in the app. *If the post is a video, the provider should provide a thumbnail of the video to be shown as an image.* | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| Text content | Optional | The main text of a post, update, etc. | String (recommended max 140 chars) |
| Timestamp | Optional | Time when the post was published. | Epoch timestamp in milliseconds |
| Is video content | Optional | Is the post a video? | boolean |
| Video duration | Optional | The duration of the video in milliseconds. | Long |
| **Profile related metadata (Optional)** ||||
| Name | Required | Profile name or id or handle, eg "John Doe", "@TeamPixel" | String(recommended max 25 chars) |
| Avatar | Required | Profile picture or avatar image of the user. **Square 1:1 image** | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| Additional Image | Optional | Profile badge. for example - verified badge **Square 1:1 image** | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| **Interactions related metadata (Optional)** ||||
| Count | Optional | Indicate the number of interactions, for example - "3.7 M.". **Note:** If both Count and Count Value are provided, Count will be used. **Note:** Partners should use either **Count** or **CountWithOptionalLabel**. | String |
| CountWithOptionalLabel | Optional | Indicate the number of interactions with an optional label, for example - "3.7 M Likes.". **Note:** If both CountWithOptionalLabel and Count Value are provided, one of them will be used. **Note:** Partners should use either **Count** or **CountWithOptionalLabel**. | String |
| Count Value | Optional | The number of interactions as a value. **Note:** Provide Count Value instead of Count if your app doesn't handle logic on how a large number should be optimized for different display sizes. If both Count and Count Value are provided, Count is used. | Long |
| Label | Optional | Indicate what the interaction label is for. For example - "Likes". | String |
| Visual | Optional | Indicate what the interaction is for. For example - Image showing Likes icon, emoji. Can provide more than 1 image, though not all may not be shown on all form factors. **Note:** Must be Square 1:1 image | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| **DisplayTimeWindow (Optional) - Set a time window for a content to be shown on the surface** ||||
| Start Timestamp | Optional | The epoch timestamp after which the content should be shown on the surface. If not set, content is eligible to be shown on the surface. | Epoch timestamp in milliseconds |
| End Timestamp | Optional | The epoch timestamp after which the content is no longer shown on the surface. If not set, content is eligible to be shown on the surface. | Epoch timestamp in milliseconds |
#### `SocialPostEntity`
| Attribute | Requirement | Description | Format |
|---|---|---|---|
| Action URI | **Required** | Deep Link to the entity in the provider app. Note: You can use deep links for attribution. [Refer to this FAQ](https://developer.android.com/guide/playcore/engage/faq#deeplinks-attribution) | URI |
| PlatformSpecificPlayback URIs | **Required** for Google TV surface | Deep Link to the entity in the provider app for platforms like Google TV and Mobile. | List of PlatformSpecificPlayback objects |
| Recommendation Reason | Optional | The justification for recommending the content to the user. | RecommendationReason object |
| Comments Summary | Optional | Summary of comments for the post. | String |
| **Post related metadata (Required)** At least one of TextContent, Image or WebContent is required ||||
| Image(s) | Optional | Image(s) should be in **portrait aspect ratio.** The UI may show only 1 image when multiple images are provided. However, the UI may provide visual indication that there are more images in the app. *If the post is a video, the provider should provide a thumbnail of the video to be shown as an image.* | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| Text content | Optional | The main text of a post, update, etc. | String (recommended max 140 chars) |
| **Video Content (Optional)** ||||
| Duration | Required | The duration of the video in milliseconds. | Long |
| Image | Required | Preview image of the video content. | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| **Link Preview (Optional)** ||||
| Link Preview - Title | Required | Text to indicate the title of the web page content | String |
| Link Preview - Hostname | Required | Text to indicate the web page owner, eg "INSIDER" | String |
| Link Preview - Image | Optional | Hero image for the web content | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| Timestamp | Optional | Time when the post was published. | Epoch timestamp in milliseconds |
| **Profile related metadata (Optional)** ||||
| Name | Required | Profile name or id or handle, eg "John Doe", "@TeamPixel." | String(recommended max 25 chars) |
| Additional Text | Optional | Could be used as profile id or handle or additional metadata For example "@John-Doe", "5M followers", "You might like", "Trending", "5 new posts" | String(recommended max 40 chars) |
| Avatar | Required | Profile picture or avatar image of the user. **Square 1:1 image** | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| Additional Image | Optional | Profile badge, for example - verified badge **Square 1:1 image** | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| **Interactions related metadata (Optional)** ||||
| Count | Required | Indicate the number of interactions, for example - "3.7 M." **Note:** Partners should use either **Count** or **CountWithOptionalLabel**. | String |
| CountWithOptionalLabel | Required | Indicate the number of interactions with an optional label, for example - "3.7 M Likes." **Note:** Partners should use either **Count** or **CountWithOptionalLabel**. | String |
| Label | Optional If not provided, **Visual** must be provided. | Indicate what the interaction is for. For example - "Likes." | String (recommended max 20 chars for count + label combined) |
| Visual | Optional If not provided, **Label** must be provided. | Indicate what the interaction is for. For example - Image showing Likes icon, emoji. Can provide more than 1 image, though not all may not be shown on all form factors. **Square 1:1 image** | See [Image Specifications](https://developer.android.com/guide/playcore/engage/social#image-specs) for guidance. |
| **DisplayTimeWindow (Optional) - Set a time window for a content to be shown on the surface** ||||
| Start Timestamp | Optional | The epoch timestamp after which the content should be shown on the surface. If not set, content is eligible to be shown on the surface. | Epoch timestamp in milliseconds |
| End Timestamp | Optional | The epoch timestamp after which the content is no longer shown on the surface. If not set, content is eligible to be shown on the surface. | Epoch timestamp in milliseconds |
#### Image specifications
The images are required to be hosted on public CDNs so that Google can access
them.
*File formats*
PNG, JPG, static GIF, WebP
*Maximum file size*
5120 KB
*Additional recommendations*
- **Image safe area:** Put your important content in the center 80% of the image.
- Use a transparent background so that the image can be properly displayed in Dark and Light theme settings.
### Step 2: Provide Cluster data
It is recommended to have the content publish job executed in the background
(for example, using [WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager))
and scheduled on a regular basis or on an event basis (for example, every time
the user opens the app or when the user just followed a new account)
`AppEngageSocialClient` is responsible for publishing social clusters.
There are following APIs to publish clusters in the client:
- `isServiceAvailable`
- `publishRecommendationClusters`
- `publishUserAccountManagementRequest`
- `updatePublishStatus`
- `deleteRecommendationsClusters`
- `deleteUserManagementCluster`
- `deleteClusters`
#### `isServiceAvailable`
This API is used to check if the service is available for integration and
whether the content can be presented on the device.
##### For Engage SDK v1.6.0 and higher (Recommended)
You can check the service availability for every cluster type that you intend to
publish. The `isServiceAvailable` API accepts a request object,
`ServiceAvailabilityRequest`, which contains the cluster types for which service
availability needs to be checked. You can find the `ClusterType` enum values
required for `ServiceAvailabilityRequest` from the following table.
| Cluster Type | Cluster Type Constant | Integer Value |
|---|---|---|
| Unknown | `TYPE_UNKNOWN` | 0 |
| Recommendation Cluster | `TYPE_RECOMMENDATION` | 1 |
| Featured Cluster | `TYPE_FEATURED` | 2 |
| Continuation Cluster | `TYPE_CONTINUATION` | 3 |
| User Management Cluster | `TYPE_ENGAGEMENT` | 8 |
| Subscription Cluster | `TYPE_SUBSCRIPTION` | 12 |
### Kotlin
val request = ServiceAvailabilityRequest.Builder()
.addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
.addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
.build()
client.isServiceAvailable(request).addOnCompleteListener { task ->
if (task.isSuccessful) {
val availabilityMap = task.result
if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
// Proceed with publishing continuation content
}
if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
// Proceed with publishing recommendation content
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
### Java
ServiceAvailabilityRequest request =
new ServiceAvailabilityRequest.Builder()
.addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
.addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
.build();
client.isServiceAvailable(request).addOnCompleteListener(task -> {
if (task.isSuccessful()) {
Map<Integer, Boolean> availabilityMap = task.getResult();
if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
// Proceed with publishing continuation content
}
if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
// Proceed with publishing recommendation content
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
});
###### Conditional Service Availability Feature
Some integrated apps request a special configuration that enables and disables
the Engage service intermittently in order to reduce their serving cost. This
intermittent content ingestion strategy, although possible, negatively affects
the user and the product -- stale content will not be presented and some surfaces
will not be served at all.
Starting with v1.6.0, the Engage SDK allows checking availability for specific
cluster types. If you are interested in opting into this feature for any cluster type,
please contact engage-developers@google.com.
##### For SDK versions prior to v1.6.0 (Deprecated)
### Kotlin
client.isServiceAvailable.addOnCompleteListener { task ->
if (task.isSuccessful) {
// Handle IPC call success
if(task.result) {
// Service is available on the device, proceed with content publish
// calls.
} else {
// Service is not available, no further action is needed.
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
### Java
client.isServiceAvailable().addOnCompleteListener(task - > {
if (task.isSuccessful()) {
// Handle success
if(task.getResult()) {
// Service is available on the device, proceed with content publish
// calls.
} else {
// Service is not available, no further action is needed.
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
});
> [!NOTE]
> **Note:** We highly recommend keeping a periodic job running to check if the service becomes available at a later point in time. The availability of the service may change with Android version upgrades, app upgrades, installs, and uninstalls. By ensuring periodic job checks at a certain time interval, data can be published once the service becomes available.
#### `publishRecommendationClusters`
This API is used to publish a list `RecommendationCluster` objects.
A `RecommendationCluster` object can have the following attributes:
| Attribute | Requirement | Description |
|---|---|---|
| List of SocialPostEntity, or PortraitMediaEntity | **Required** | A list of entities that make up the recommendations for this Recommendation Cluster. Entities in a single cluster must be of the same type. |
| Title | **Required** | The title for the Recommendation Cluster (for example, *Latest from your friends*). **Recommended text size: under 25 chars** (Text that is too long may show ellipses) |
| Subtitle | Optional | The subtitle for the Recommendation Cluster. |
| Action Uri | Optional | The deep link to the page in the partner app where users can see the complete list of recommendations. Note: You can use deep links for attribution. [Refer to this FAQ](https://developer.android.com/guide/playcore/engage/faq#deeplinks-attribution) |
> [!IMPORTANT]
> **Important:** The publish APIs are upsert APIs; it replaces the existing content. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.
> [!IMPORTANT]
> **Important:** For social apps, it's critical to update recommendations after each app usage. Social app users are more interested in the most recent recommendations and ideally would like to see a post at most once.
### Kotlin
client.publishRecommendationClusters(
PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(
RecommendationCluster.Builder()
.addEntity(entity1)
.addEntity(entity2)
.setTitle("Latest from your friends")
.build())
.build())
### Java
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(
new RecommendationCluster.Builder()
.addEntity(entity1)
.addEntity(entity2)
.setTitle("Latest from your friends")
.build())
.build());
When the service receives the request, the following actions take place within
one transaction:
- All existing Recommendation Cluster data is removed.
- Data from the request is parsed and stored in new Recommendation Clusters.
In case of an error, the entire request is rejected and the existing state is
maintained.
#### `publishUserAccountManagementRequest`
This API is used to publish a Sign In card . The signin action directs users to
the app's sign in page so that the app can publish content (or provide more
personalized content)
The following metadata is part of the Sign In Card -
| Attribute | Requirement | Description |
|---|---|---|
| Action Uri | Required | Deeplink to Action (i.e. navigates to app sign in page) |
| Image | Optional - If not provided, Title must be provided | Image Shown on the Card 16x9 aspect ratio images with a resolution of 1264x712 |
| Title | Optional - If not provided, Image must be provided | Title on the Card |
| Action Text | Optional | Text Shown on the CTA (i.e. Sign in) |
| Subtitle | Optional | Optional Subtitle on the Card |
> [!IMPORTANT]
> **Important:** The publish APIs are upsert APIs; it replaces the existing content. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently.
### Kotlin
var SIGN_IN_CARD_ENTITY =
SignInCardEntity.Builder()
.addPosterImage(
Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(500)
.setImageWidthInPixel(500)
.build())
.setActionText("Sign In")
.setActionUri(Uri.parse("http://xx.com/signin"))
.build()
client.publishUserAccountManagementRequest(
PublishUserAccountManagementRequest.Builder()
.setSignInCardEntity(SIGN_IN_CARD_ENTITY)
.build());
### Java
SignInCardEntity SIGN_IN_CARD_ENTITY =
new SignInCardEntity.Builder()
.addPosterImage(
new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(500)
.setImageWidthInPixel(500)
.build())
.setActionText("Sign In")
.setActionUri(Uri.parse("http://xx.com/signin"))
.build();
client.publishUserAccountManagementRequest(
new PublishUserAccountManagementRequest.Builder()
.setSignInCardEntity(SIGN_IN_CARD_ENTITY)
.build());
When the service receives the request, the following actions take place within
one transaction:
- Existing `UserAccountManagementCluster` data from the developer partner is removed.
- Data from the request is parsed and stored in the updated UserAccountManagementCluster Cluster.
In case of an error, the entire request is rejected and the existing state is
maintained.
#### `updatePublishStatus`
If for any internal business reason, none of the clusters is published,
we **strongly recommend** updating the publish status using the
**updatePublishStatus** API.
This is important because :
- Providing the status in all scenarios, even when the content is published (STATUS == PUBLISHED), is critical to populate dashboards that use this explicit status to convey the health and other metrics of your integration.
- If no content is published but the integration status isn't broken (STATUS == NOT_PUBLISHED), Google can avoid triggering alerts in the app health dashboards. It confirms that content is not published due to an **expected** situation from the provider's standpoint.
- It helps developers provide insights into when the data is published versus not.
- Google may use the status codes to nudge the user to do certain actions in the app so they can see the app content or overcome it.
The list of eligible publish status codes are :
// Content is published
AppEngagePublishStatusCode.PUBLISHED,
// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,
// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,
// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,
// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,
// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,
// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,
// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,
// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER
If the content is not published due to a user not logged in,
Google would recommend publishing the Sign In Card.
If for any reason providers are not able to publish the Sign In Card
then we recommend calling the **updatePublishStatus** API
with the status code **NOT_PUBLISHED_REQUIRES_SIGN_IN**
### Kotlin
client.updatePublishStatus(
PublishStatusRequest.Builder()
.setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
.build())
### Java
client.updatePublishStatus(
new PublishStatusRequest.Builder()
.setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
.build());
#### `deleteRecommendationClusters`
This API is used to delete the content of Recommendation Clusters.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteRecommendationClusters()
### Java
client.deleteRecommendationClusters();
When the service receives the request, it removes the existing data from the
Recommendation Clusters. In case of an error, the entire request is rejected
and the existing state is maintained.
#### `deleteUserManagementCluster`
This API is used to delete the content of UserAccountManagement Cluster.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteUserManagementCluster()
### Java
client.deleteUserManagementCluster();
When the service receives the request, it removes the existing data from the
UserAccountManagement Cluster. In case of an error, the entire request is
rejected and the existing state is maintained.
#### `deleteClusters`
This API is used to delete the content of a given cluster type.
> [!IMPORTANT]
> **Important:** Delete APIs should only be called when there is no content to publish. **Don't** call delete and publish APIs subsequently to replace the content as the publish APIs do that inherently. Reach out to [`engage-developers@google.com`](mailto:engage-developers@google.com) before using delete APIs.
### Kotlin
client.deleteClusters(
DeleteClustersRequest.Builder()
.addClusterType(ClusterType.TYPE_RECOMMENDATION)
...
.build())
### Java
client.deleteClusters(
new DeleteClustersRequest.Builder()
.addClusterType(ClusterType.TYPE_RECOMMENDATION)
...
.build());
When the service receives the request, it removes the existing data from all
clusters matching the specified cluster types. Clients can choose to pass one or
many cluster types. In case of an error, the entire request is rejected and the
existing state is maintained.
#### Error handling
It is highly recommended to listen to the task result from the publish APIs such
that a follow-up action can be taken to recover and resubmit an successful task.
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(...)
.build())
.addOnCompleteListener(
task -> {
if (task.isSuccessful()) {
// do something
} else {
Exception exception = task.getException();
if (exception instanceof AppEngageException) {
@AppEngageErrorCode
int errorCode = ((AppEngageException) exception).getErrorCode();
if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
// do something
}
}
}
});
The error is returned as an `AppEngageException` with the cause included as an
error code.
| Error code | Error name | Note |
|---|---|---|
| `1` | `SERVICE_NOT_FOUND` | The service is not available on the given device. |
| `2` | `SERVICE_NOT_AVAILABLE` | The service is available on the given device, but it is not available at the time of the call (for example, it is explicitly disabled). |
| `3` | `SERVICE_CALL_EXECUTION_FAILURE` | The task execution failed due to threading issues. In this case, it can be retried. |
| `4` | `SERVICE_CALL_PERMISSION_DENIED` | The caller is not allowed to make the service call. |
| `5` | `SERVICE_CALL_INVALID_ARGUMENT` | The request contains invalid data (for example, more than the allowed number of clusters). |
| `6` | `SERVICE_CALL_INTERNAL` | There is an error on the service side. |
| `7` | `SERVICE_CALL_RESOURCE_EXHAUSTED` | The service call is made too frequently. |
### Step 3: Handle broadcast intents
In addition to making publish content API calls through a job, it is also
required to set up a
[`BroadcastReceiver`](https://developer.android.com/reference/android/content/BroadcastReceiver) to receive
the request for a content publish.
The goal of broadcast intents is mainly for app reactivation and forcing data
sync. Broadcast intents are not designed to be sent very frequently. It is only
triggered when the Engage Service determines the content might be stale (for
example, a week old). That way, there is more confidence that the user can have
a fresh content experience, even if the application has not been executed for a
long period of 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.
### Kotlin
class AppEngageBroadcastReceiver : BroadcastReceiver(){
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
// broadcast is received
}
fun registerBroadcastReceivers(context: Context){
var context = context
context = context.applicationContext
// Register Recommendation Cluster Publish Intent
context.registerReceiver(AppEngageBroadcastReceiver(),
IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null)
}
### Java
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
}
public static void registerBroadcastReceivers(Context context) {
context = context.getApplicationContext();
// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION),
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null);
}
- 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.
<application>
<receiver
android:name=".AppEngageBroadcastReceiver"
android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
android:exported="true"
android:enabled="true">
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
</intent-filter>
</receiver>
</application>
The following [intents](https://developer.android.com/reference/android/content/Intent) will be sent by the
service:
- `com.google.android.engage.action.PUBLISH_RECOMMENDATION` It is recommended to start a `publishRecommendationClusters` call when receiving this intent.
## Integration workflow
For a step-by-step guide on verifying your integration after it is complete, see
[Engage developer integration workflow](https://developer.android.com/guide/playcore/engage/workflow).
## FAQs
See [Engage SDK Frequently Asked Questions](https://developer.android.com/guide/playcore/engage/faq) for
FAQs.
## Contact
Contact
[`engage-developers@google.com`](mailto:engage-developers@google.com) if there are
any questions during the integration process. Our team will reply as soon as
possible.
## Next steps
After completing this integration, your next steps are as follows:
- Send an email to [`engage-developers@google.com`](mailto:engage-developers@google.com) and attach your integrated APK that is ready for testing by Google.
- Google performs a verification and reviews internally to make sure the integration works as expected. If changes are needed, Google contacts you with any necessary details.
- When testing is complete and no changes are needed, Google contacts you to notify you that you can start publishing the updated and integrated APK to the Play Store.
- After Google has confirmed that your updated APK has been published to the Play Store, your **Recommendation**, clusters will be published and visible to users.

1396
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/travel.md Normal file
View File

File diff suppressed because it is too large Load Diff

19
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/tv/continue-watching/index.md Normal file
View File

@@ -0,0 +1,19 @@
Continue watching leverages the **Continuation cluster** to show unfinished
videos, and next episodes to be watched from the same TV show, from multiple
apps in one UI grouping. You can feature your entities in this continuation
cluster. Follow this guide to learn how to enhance user engagement through the
continue watching experience using [Engage SDK](https://developer.android.com/guide/playcore/engage).
You manage the continuation cluster by using the client API in a TV app or from
a REST API:
- [Integrate continue watching on Android TV](https://developer.android.com/guide/playcore/engage/tv/continue-watching/client)
- [Integrate continue watching using REST API](https://developer.android.com/guide/playcore/engage/tv/continue-watching/rest)
## Sample code
This [sample app](https://github.com/googlesamples/tv-video-discovery-samples) demonstrates how you can integrate with Engage SDK
to send personalized user data to Google. It shows how to build a common module
that you can import in both mobile and TV apps. The sample also illustrates
when to call the publish and delete APIs, as well as how to use Workers to
make these calls.

353
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/tv/entitlements.md Normal file
View File

@@ -0,0 +1,353 @@
This guide contains instructions for developers to share app subscription and
entitlement data with Google TV using [Engage SDK](https://developer.android.com/guide/playcore/engage). Users can find
content they are entitled to and enable Google TV to deliver highly relevant
content recommendations to users, directly within Google TV experiences on TV,
mobile, and tablet.
## Prerequisites
> [!IMPORTANT]
> **Important:** [Express interest in developing with Engage](http://g.co/tv/vda).
Onboarding the media actions feed is required before you can use the device
entitlement API. If you haven't already done so, complete the [media actions
feed](https://developers.google.com/actions/media?authuser=0) onboarding process.
## Pre-work
Complete the [Pre-work](https://developer.android.com/guide/playcore/engage/tv/getting-started#pre-work) instructions in the Getting Started guide.
1. Publish subscription information on the following events:
1. User logs in to your app.
2. User switches between profiles (if profiles are supported).
3. User purchases a new subscription.
4. User upgrades an existing subscription.
5. User subscription expires.
## Integration
This section provides the necessary code examples and instructions for
implementing `SubscriptionEntity` to manage various subscription types.
### Common tier subscription
For users with basic subscriptions to media provider services, for example, a
service that has one subscription tier that grants access to all the paid
content, provide these essential details:
1. `SubscriptionType`: Clearly indicate the specific subscription plan the user
has.
- `SUBSCRIPTION_TYPE_ACTIVE`: User has an active paid subscription.
- `SUBSCRIPTION_TYPE_ACTIVE_TRIAL`: User has a trial subscription.
- `SUBSCRIPTION_TYPE_INACTIVE`: User has an account but no active subscription or trial.
> [!IMPORTANT]
> **Important:** Only users with `SUBSCRIPTION_TYPE_ACTIVE` or `SUBSCRIPTION_TYPE_ACTIVE_TRIAL` are eligible for personalized content recommendations based on their subscription.
2. `ExpirationTimeMillis`: Optional time in milliseconds. Specify when the
subscription is set to expire.
3. `ProviderPackageName`: Specify the package name of the app that handles the
subscription.
Example for the sample media provider feed.
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Basic common name",
"commonTier": true
}
The following example creates a `SubscriptionEntity` for a user:
val subscription = SubscriptionEntity.Builder()
setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build()
### Premium subscription
If app offer multi-tiered premium subscription packages, which includes expanded
content or features beyond the common tier, represent this by adding one or more
entitlements to Subscription.
This entitlement has the following fields:
1. `Identifier`: Required identifier string for this entitlement. This must match one of the [entitlement identifiers](https://developers.google.com/actions/media/concepts/access-requirements#entitlement-identifier) (note that this isn't the ID field) provided in the media provider's feed published to Google TV.
2. `Name`: This is auxiliary information and is used for entitlement matching. While optional, providing a human readable entitlement name enhances understanding of user entitlements for both developers and support teams. For example: Sling Orange.
3. `ExpirationTimeMillis`: Optionally specify the expiration time in milliseconds for this entitlement, if it differs from the subscription expiration time. By default, the entitlement will expire with the expiry of subscription.
For the following sample media provider feed snippet:
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Example entitlement name",
"commonTier": false,
// match this identifier in your API. This is the crucial
// entitlement identifier used for recommendation purpose.
"identifier": "example.com:entitlementString1"
}
The following example creates a `SubscriptionEntity` for a subscribed user:
// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
// matches with the identifier in media provider feed
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
.build()
)
.build()
// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
// You may set the expiration time for entitlement
// December 15, 2025 10:00:00 AM in milliseconds
.setExpirationTimeMillis(1765792800000)
.build())
.build()
### Subscription for linked service package
While subscriptions typically belong to the originating app's media provider, a
subscription can be attributed to a linked service package by specifying the
linked service package name within the subscription.
Following code sample demonstrate how to create user subscription.
// Subscription for linked service package
val subscription = SubscriptionEntity.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build()
In addition, if the user has another subscription to a subsidiary service, add
another subscription and set the linked service package name accordingly.
// Subscription for linked service package
val linkedSubscription = Subscription.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("linked service package name")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.addBundledSubscription(
BundledSubscription.Builder()
.setBundledSubscriptionProviderPackageName(
"bundled-subscription-package-name"
)
.setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
.setExpirationTimeMillis(111)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setExpirationTimeMillis(111)
.setDisplayName("Silver subscription")
.setEntitlementId("subscription.tier.platinum")
.build()
)
.build()
)
.build()
Optionally, add entitlements to a linked service subscription too.
### Provide subscription set
Run the content publish job while the app is in the foreground.
Use the `publishSubscriptionCluster()` method, from the
`AppEngagePublishClient` class, to publish a `SubscriptionCluster` object.
Make sure to initialize the client and check for service availability as
described in the [Getting Started guide](https://developer.android.com/guide/playcore/engage/tv/getting-started#common-integration).
client.publishSubscription(
PublishSubscriptionRequest.Builder()
.setAccountProfile(accountProfile)
.setSubscription(subscription)
.build()
)
Use `setSubscription()` to verify that user should have only one subscription to
the service.
Use `addLinkedSubscription()`, or `addLinkedSubscriptions()` which accept a list
of linked subscriptions, to enable user to have zero or more linked
subscriptions.
When the service receives the request, a new entry is created and the old entry
is automatically deleted after 60 days. The system always uses the latest entry.
In case of an error, the entire request is rejected and the existing state is
maintained.
### Keep subscription up-to-date
1. To provide immediate updates upon changes, call
`publishSubscriptionCluster` whenever a user's subscription state changes
like activation, deactivation, upgrades, downgrades.
2. To provide regular validation for ongoing accuracy, call
`publishSubscriptionCluster` at least once per month.
> [!NOTE]
> **Note:** As Google TV automatically deletes historical data beyond 60 days to safeguard user privacy, publishing user subscription data at least once per month verify the validity of data. Unlike `publishContinuationCluster` for continue watching data, don't set `syncAcrossDevices` flag, as subscription information is by default used to provide content across all devices.
3. To delete the Engage data, manually delete a user's data from the
Google TV server before the standard 60-day retention period, use the
`client.deleteClusters` method. This deletes all existing Engage
data for the account profile, or for the entire account depending on the
given [`DeleteReason`](https://developer.android.com/reference/com/google/android/engage/service/DeleteReason).
The following code snippet shows how to remove a user subscription:
// If the user logs out from your media app, you must make the following call
// to remove subscription and other Engage data from the current
// google TV device.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
.build()
)
The following code snippet demonstrates removal of user subscription
when user revokes the consent:
// If the user revokes the consent to share across device, make the call
// to remove subscription and other Engage data from all google
// TV devices.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
.build()
)
Following code demonstrates how to remove subscription data on user profile
deletion.
// If the user delete a specific profile, you must make the following call
// to remove subscription data and other Engage data.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION)
.build()
)
### Testing
This section provides a step-by-step guide for testing subscription
implementation. Verify data accuracy and proper functionality before launch.
#### Publish Integration checklist
1. Publishing should happen when the app is in the foreground and user the
actively interacting with it.
2. Publish when:
- User logs in for the first time.
- User changes profile (if profiles are supported).
- User purchases new subscription.
- User upgrades subscription.
- User subscription expires.
3. Check if app is correctly calling `isServiceAvailable()` and
`publishClusters()` APIs in logcat, on the publishing events.
4. Verify that data is visible in the verification app. The verification app
should display subscription as a separate row. When the publish API is
invoked, the data should show up in the verification app.
> [!IMPORTANT]
> **Important:** Verify that the [Engage Service Flag](https://developer.android.com/guide/playcore/engage/workflow#switch-to-prod) is **not** set to production.
5. Go to app and perform each of the following actions:
- Sign in.
- Switch between profiles (if supported).
- Purchase a new subscription.
- Upgrade an existing subscription.
- Expire the subscription.
#### Verify integration
To test your integration, use the [verification app](https://developer.android.com/guide/playcore/engage/tv/getting-started#testing).
1. For each of the events, check if app has invoked the `publishSubscription` API. Verify the published data in the verification app. **Verify that everything is green in verification app**
2. If all the entity's information is correct, it shows an "All Good" green
check in all entities.
![Verification App Success Screenshot](https://developer.android.com/static/images/guide/playcore/engage/ett-va-success.png) **Figure 1.** Successful subscription
3. Problems are also highlighted in verification app
![Verification App Error Screenshot](https://developer.android.com/static/images/guide/playcore/engage/ett-va-error.png) **Figure 2.**Subscription unsuccessful
4. To see the problems in the bundled subscription, use the TV remote to focus
on that specific bundled subscription and click to see the problems. You
might have to first focus on the row and move to the right to find Bundled
Subscription card. The problems are highlighted as red as shown in Fig 3.
Also, use the remote to move down to see problems in the entitlements within
bundled subscription
![Verification App Error Details Screenshot](https://developer.android.com/static/images/guide/playcore/engage/ett-va-error-details.png) **Figure 3.**Subscription Errors
5. To see the problems in the entitlement, use the TV remote to focus on that
specific entitlement and click to see the problems. The problems are
highlighted as red.
![Verification App Error Screenshot](https://developer.android.com/static/images/guide/playcore/engage/ett-va-details.png) **Figure 4.**Subscription Error Details

173
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/tv/getting-started.md Normal file
View File

@@ -0,0 +1,173 @@
<br />
[Engage SDK](https://developer.android.com/guide/playcore/engage) lets you deliver personalized recommendations
and continuation content directly to users on Google TV.
This guide covers how to get started with Engage SDK integrations for TV. After
you complete the pre-work on this page, you can integrate one or more
of the TV features:
- [Publish continue watching data](https://developer.android.com/guide/playcore/engage/tv/continue-watching)
- [Publish device entitlements](https://developer.android.com/guide/playcore/engage/tv/entitlements)
- [Publish recommendations](https://developer.android.com/guide/playcore/engage/tv/recommendations)
## Pre-work
Before you begin, complete the following steps:
1. [Express interest in developing with Engage SDK](http://g.co/tv/engage) to enroll in
the program, if eligible.
2. Verify that your app targets Android 4.4 (API level 19) or higher for this
integration.
3. Add the `com.google.android.engage` library to your app:
There are separate SDKs to use in the integration: one for mobile apps and
one for TV apps.
### Mobile
dependencies {
implementation 'com.google.android.engage:engage-core:1.6.0'
}
### TV
dependencies {
implementation 'com.google.android.engage:engage-tv:1.0.6'
}
4. Add permission for `WRITE_EPG_DATA` for TV APK
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
5. Verify reliable content publishing by using a background service, such as
`androidx.work`, for scheduling.
6. Test your implementation using the verification app as outlined in the
[Testing section](https://developer.android.com/guide/playcore/engage/tv/getting-started#testing).
7. In your production app, set the Engage service environment to production in
the `AndroidManifest.xml` file.
<meta-data
android:name="com.google.android.engage.service.ENV"
android:value="PRODUCTION" />
> [!IMPORTANT]
> **Important:** The Engage service environment declaration is only needed for your release build. For your local testing with the verification app, don't include this element.
## Common integration steps
### Initialize the client
Use `AppEngagePublishClient` to interact with the service. Always check if the
service is available before publishing.
val client = AppEngagePublishClient(context)
client.isServiceAvailable().addOnCompleteListener { task ->
if (task.isSuccessful && task.result) {
// Service is available, proceed with publishing
} else {
// Service is not available or call failed
}
}
### Create an account profile
`AccountProfile` identifies the user. You can specify an account ID, and
optionally a profile ID and locale.
val accountProfile = AccountProfile.Builder()
.setAccountId("your_users_account_id")
.setProfileId("your_users_profile_id") // Optional
.setLocale(Locale.US.toLanguageTag()) // Optional, e.g., "en-US"
.build()
An `AccountProfile` must be provided with an account ID in order for content to
be synchronized between devices. See [Cross-device syncing](https://developer.android.com/guide/playcore/engage/tv/continue-watching/client#cross-device_syncing).
## Testing
To test your integration, download the verification app:
[Download verification
app](https://developer.android.com/guide/playcore/engage/tv/getting-started#lightbox-trigger)
The verification app is an Android app with capabilities to help you test your
integration. It let you to check data accuracy and proper functionality by
verifying published data and broadcast intents before launch.
1. Install and open the Engage Verification app.
2. If the value of `isServiceAvailable` is `false` in the verification app, click the **Toggle** button within the verification app to set it to `true`.
3. Enter the package name of your app. It automatically shows the published data.
4. Run your app and perform publishing actions, such as logging in or watching a video.
5. Verify that the data shows up in the verification app.
## Download
Before downloading, you must agree to the following terms and conditions.
## Terms and Conditions
This is the Android Software Development Kit License Agreement
### 1. Introduction
1.1 The Android Software Development Kit (referred to in the License Agreement as the "SDK" and specifically including the Android system files, packaged APIs, and Google APIs add-ons) is licensed to you subject to the terms of the License Agreement. The License Agreement forms a legally binding contract between you and Google in relation to your use of the SDK. 1.2 "Android" means the Android software stack for devices, as made available under the Android Open Source Project, which is located at the following URL: https://source.android.com , as updated from time to time. 1.3 A "compatible implementation" means any Android device that (i) complies with the Android Compatibility Definition document, which can be found at the Android compatibility website (https://source.android.com/compatibility) and which may be updated from time to time; and (ii) successfully passes the Android Compatibility Test Suite (CTS). 1.4 "Google" means Google LLC, organized under the laws of the State of Delaware, USA, and operating under the laws of the USA with principal place of business at 1600 Amphitheatre Parkway, Mountain View, CA 94043, USA.
### 2. Accepting this License Agreement
2.1 In order to use the SDK, you must first agree to the License Agreement. You may not use the SDK if you do not accept the License Agreement. 2.2 By clicking to accept and/or using this SDK, you hereby agree to the terms of the License Agreement. 2.3 You may not use the SDK and may not accept the License Agreement if you are a person barred from receiving the SDK under the laws of the United States or other countries, including the country in which you are resident or from which you use the SDK. 2.4 If you are agreeing to be bound by the License Agreement on behalf of your employer or other entity, you represent and warrant that you have full legal authority to bind your employer or such entity to the License Agreement. If you do not have the requisite authority, you may not accept the License Agreement or use the SDK on behalf of your employer or other entity.
### 3. SDK License from Google
3.1 Subject to the terms of the License Agreement, Google grants you a limited, worldwide, royalty-free, non-assignable, non-exclusive, and non-sublicensable license to use the SDK solely to develop applications for compatible implementations of Android. 3.2 You may not use this SDK to develop applications for other platforms (including non-compatible implementations of Android) or to develop another SDK. You are of course free to develop applications for other platforms, including non-compatible implementations of Android, provided that this SDK is not used for that purpose. 3.3 You agree that Google or third parties own all legal right, title and interest in and to the SDK, including any Intellectual Property Rights that subsist in the SDK. "Intellectual Property Rights" means any and all rights under patent law, copyright law, trade secret law, trademark law, and any and all other proprietary rights. Google reserves all rights not expressly granted to you. 3.4 You may not use the SDK for any purpose not expressly permitted by the License Agreement. Except to the extent required by applicable third party licenses, you may not copy (except for backup purposes), modify, adapt, redistribute, decompile, reverse engineer, disassemble, or create derivative works of the SDK or any part of the SDK. 3.5 Use, reproduction and distribution of components of the SDK licensed under an open source software license are governed solely by the terms of that open source software license and not the License Agreement. 3.6 You agree that the form and nature of the SDK that Google provides may change without prior notice to you and that future versions of the SDK may be incompatible with applications developed on previous versions of the SDK. You agree that Google may stop (permanently or temporarily) providing the SDK (or any features within the SDK) to you or to users generally at Google's sole discretion, without prior notice to you. 3.7 Nothing in the License Agreement gives you a right to use any of Google's trade names, trademarks, service marks, logos, domain names, or other distinctive brand features. 3.8 You agree that you will not remove, obscure, or alter any proprietary rights notices (including copyright and trademark notices) that may be affixed to or contained within the SDK.
### 4. Use of the SDK by You
4.1 Google agrees that it obtains no right, title or interest from you (or your licensors) under the License Agreement in or to any software applications that you develop using the SDK, including any intellectual property rights that subsist in those applications. 4.2 You agree to use the SDK and write applications only for purposes that are permitted by (a) the License Agreement and (b) any applicable law, regulation or generally accepted practices or guidelines in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries). 4.3 You agree that if you use the SDK to develop applications for general public users, you will protect the privacy and legal rights of those users. If the users provide you with user names, passwords, or other login information or personal information, you must make the users aware that the information will be available to your application, and you must provide legally adequate privacy notice and protection for those users. If your application stores personal or sensitive information provided by users, it must do so securely. If the user provides your application with Google Account information, your application may only use that information to access the user's Google Account when, and for the limited purposes for which, the user has given you permission to do so. 4.4 You agree that you will not engage in any activity with the SDK, including the development or distribution of an application, that interferes with, disrupts, damages, or accesses in an unauthorized manner the servers, networks, or other properties or services of any third party including, but not limited to, Google or any mobile communications carrier. 4.5 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any data, content, or resources that you create, transmit or display through Android and/or applications for Android, and for the consequences of your actions (including any loss or damage which Google may suffer) by doing so. 4.6 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any breach of your obligations under the License Agreement, any applicable third party contract or Terms of Service, or any applicable law or regulation, and for the consequences (including any loss or damage which Google or any third party may suffer) of any such breach.
### 5. Your Developer Credentials
5.1 You agree that you are responsible for maintaining the confidentiality of any developer credentials that may be issued to you by Google or which you may choose yourself and that you will be solely responsible for all applications that are developed under your developer credentials.
### 6. Privacy and Information
6.1 In order to continually innovate and improve the SDK, Google may collect certain usage statistics from the software including but not limited to a unique identifier, associated IP address, version number of the software, and information on which tools and/or services in the SDK are being used and how they are being used. Before any of this information is collected, the SDK will notify you and seek your consent. If you withhold consent, the information will not be collected. 6.2 The data collected is examined in the aggregate to improve the SDK and is maintained in accordance with Google's Privacy Policy, which is located at the following URL: https://policies.google.com/privacy 6.3 Anonymized and aggregated sets of the data may be shared with Google partners to improve the SDK.
### 7. Third Party Applications
7.1 If you use the SDK to run applications developed by a third party or that access data, content or resources provided by a third party, you agree that Google is not responsible for those applications, data, content, or resources. You understand that all data, content or resources which you may access through such third party applications are the sole responsibility of the person from which they originated and that Google is not liable for any loss or damage that you may experience as a result of the use or access of any of those third party applications, data, content, or resources. 7.2 You should be aware the data, content, and resources presented to you through such a third party application may be protected by intellectual property rights which are owned by the providers (or by other persons or companies on their behalf). You may not modify, rent, lease, loan, sell, distribute or create derivative works based on these data, content, or resources (either in whole or in part) unless you have been specifically given permission to do so by the relevant owners. 7.3 You acknowledge that your use of such third party applications, data, content, or resources may be subject to separate terms between you and the relevant third party. In that case, the License Agreement does not affect your legal relationship with these third parties.
### 8. Using Android APIs
8.1 Google Data APIs 8.1.1 If you use any API to retrieve data from Google, you acknowledge that the data may be protected by intellectual property rights which are owned by Google or those parties that provide the data (or by other persons or companies on their behalf). Your use of any such API may be subject to additional Terms of Service. You may not modify, rent, lease, loan, sell, distribute or create derivative works based on this data (either in whole or in part) unless allowed by the relevant Terms of Service. 8.1.2 If you use any API to retrieve a user's data from Google, you acknowledge and agree that you will retrieve data only with the user's explicit consent and only when, and for the limited purposes for which, the user has given you permission to do so. If you use the Android Recognition Service API, documented at the following URL: https://developer.android.com/reference/android/speech/RecognitionService, as updated from time to time, you acknowledge that the use of the API is subject to the Data Processing Addendum for Products where Google is a Data Processor, which is located at the following URL: https://privacy.google.com/businesses/gdprprocessorterms/, as updated from time to time. By clicking to accept, you hereby agree to the terms of the Data Processing Addendum for Products where Google is a Data Processor.
### 9. Terminating this License Agreement
9.1 The License Agreement will continue to apply until terminated by either you or Google as set out below. 9.2 If you want to terminate the License Agreement, you may do so by ceasing your use of the SDK and any relevant developer credentials. 9.3 Google may at any time, terminate the License Agreement with you if: (A) you have breached any provision of the License Agreement; or (B) Google is required to do so by law; or (C) the partner with whom Google offered certain parts of SDK (such as APIs) to you has terminated its relationship with Google or ceased to offer certain parts of the SDK to you; or (D) Google decides to no longer provide the SDK or certain parts of the SDK to users in the country in which you are resident or from which you use the service, or the provision of the SDK or certain SDK services to you by Google is, in Google's sole discretion, no longer commercially viable. 9.4 When the License Agreement comes to an end, all of the legal rights, obligations and liabilities that you and Google have benefited from, been subject to (or which have accrued over time whilst the License Agreement has been in force) or which are expressed to continue indefinitely, will be unaffected by this cessation, and the provisions of paragraph 14.7 will continue to apply to such rights, obligations and liabilities indefinitely.
### 10. DISCLAIMER OF WARRANTIES
10.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT YOUR USE OF THE SDK IS AT YOUR SOLE RISK AND THAT THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY KIND FROM GOOGLE. 10.2 YOUR USE OF THE SDK AND ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE USE OF THE SDK IS AT YOUR OWN DISCRETION AND RISK AND YOU ARE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM SUCH USE. 10.3 GOOGLE FURTHER EXPRESSLY DISCLAIMS ALL WARRANTIES AND CONDITIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
### 11. LIMITATION OF LIABILITY
11.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT GOOGLE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS WILL NOT BE LIABLE TO YOU UNDER ANY THEORY OF LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES THAT MAY BE INCURRED BY YOU, INCLUDING ANY LOSS OF DATA, WHETHER OR NOT GOOGLE OR ITS REPRESENTATIVES HAVE BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES ARISING.
### 12. Indemnification
12.1 To the maximum extent permitted by law, you agree to defend, indemnify and hold harmless Google, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any and all losses, liabilities, damages, costs and expenses (including reasonable attorneys fees) arising out of or accruing from (a) your use of the SDK, (b) any application you develop on the SDK that infringes any copyright, trademark, trade secret, trade dress, patent or other intellectual property right of any person or defames any person or violates their rights of publicity or privacy, and (c) any non-compliance by you with the License Agreement.
### 13. Changes to the License Agreement
13.1 Google may make changes to the License Agreement as it distributes new versions of the SDK. When these changes are made, Google will make a new version of the License Agreement available on the website where the SDK is made available.
### 14. General Legal Terms
14.1 The License Agreement constitutes the whole legal agreement between you and Google and governs your use of the SDK (excluding any services which Google may provide to you under a separate written agreement), and completely replaces any prior agreements between you and Google in relation to the SDK. 14.2 You agree that if Google does not exercise or enforce any legal right or remedy which is contained in the License Agreement (or which Google has the benefit of under any applicable law), this will not be taken to be a formal waiver of Google's rights and that those rights or remedies will still be available to Google. 14.3 If any court of law, having the jurisdiction to decide on this matter, rules that any provision of the License Agreement is invalid, then that provision will be removed from the License Agreement without affecting the rest of the License Agreement. The remaining provisions of the License Agreement will continue to be valid and enforceable. 14.4 You acknowledge and agree that each member of the group of companies of which Google is the parent will be third party beneficiaries to the License Agreement and that such other companies will be entitled to directly enforce, and rely upon, any provision of the License Agreement that confers a benefit on (or rights in favor of) them. Other than this, no other person or company will be third party beneficiaries to the License Agreement. 14.5 EXPORT RESTRICTIONS. THE SDK IS SUBJECT TO UNITED STATES EXPORT LAWS AND REGULATIONS. YOU MUST COMPLY WITH ALL DOMESTIC AND INTERNATIONAL EXPORT LAWS AND REGULATIONS THAT APPLY TO THE SDK. THESE LAWS INCLUDE RESTRICTIONS ON DESTINATIONS, END USERS AND END USE. 14.6 The rights granted in the License Agreement may not be assigned or transferred by either you or Google without the prior written approval of the other party. Neither you nor Google will be permitted to delegate their responsibilities or obligations under the License Agreement without the prior written approval of the other party. 14.7 The License Agreement, and your relationship with Google under the License Agreement, will be governed by the laws of the State of California without regard to its conflict of laws provisions. You and Google agree to submit to the exclusive jurisdiction of the courts located within the county of Santa Clara, California to resolve any legal matter arising from the License Agreement. Notwithstanding this, you agree that Google will still be allowed to apply for injunctive remedies (or an equivalent type of urgent legal relief) in any jurisdiction. *April 28, 2026* I have read and agree with the above terms and conditions <button class="button button-disabled"> Download </button> [Download](https://dl.google.com/developers/android/channels/verify_app_multiplatform_public_20260701.apk)
*verify_app_multiplatform_public_20260701.apk*

471
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/tv/recommendations.md Normal file
View File

@@ -0,0 +1,471 @@
This guide contains instructions for developers to integrate their recommended
video content, using the [Engage SDK](https://developer.android.com/guide/playcore/engage), to populate recommendations
experiences across Google surfaces, such as TV, mobile, and tablet.
Recommendation leverages the **Recommendation cluster** to show movies and TV
shows, from multiple apps in one UI grouping. Each developer partner can
broadcast a maximum **of 25 entities** in each recommendations cluster and there
can be a maximum **of 7** recommendation clusters per request.
## Pre-work
> [!IMPORTANT]
> **Important:** [Express interest in developing with Engage](http://g.co/tv/vda).
Complete the [Pre-work](https://developer.android.com/guide/playcore/engage/tv/getting-started#pre-work) instructions in the Getting Started guide.
1. Execute publishing on a foreground service.
2. Publish recommendations data at most once daily, triggered by either of
- User's first login of the day. (*or*)
- When the user starts interacting with the application.
## Integration
`AppEngagePublishClient` publishes the recommendation cluster. Use the
`publishRecommendationClusters` method to publish a recommendations object.
Make sure to initialize the client and check for service availability as
described in the [Getting Started guide](https://developer.android.com/guide/playcore/engage/tv/getting-started#common-integration).
client.publishRecommendationClusters(recommendationRequest)
### Upserting recommendation clusters
Clusters are logical grouping of the entities. The following code examples
explains how to build the clusters based on your preference and how to create a
publishing request and upsert all clusters.
The [`RecommendationClusterType`](https://developer.android.com/reference/com/google/android/engage/common/datamodel/RecommendationClusterType) determines how the
cluster will be displayed.
// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
.Builder()
.addEntity(movie1)
.addEntity(movie2)
.addEntity(movie3)
.addEntity(movie4)
.addEntity(tvShow)
// This cluster is meant to be used as an individual provider row
.setRecommendationClusterType(TYPE_PROVIDER_ROW)
.setTitle("Popular Movies")
.build()
// cluster for live TV programs
val recommendationCluster2 = RecommendationCluster
.Builder()
.addEntity(liveTvProgramEntity1)
.addEntity(liveTvProgramEntity2)
.addEntity(liveTvProgramEntity3)
.addEntity(liveTvProgramEntity4)
.addEntity(liveTvProgramEntity5)
// This cluster is meant to be used as an individual provider row
.setRecommendationClusterType(TYPE_PROVIDER_ROW)
.setTitle("Popular Live TV Programs")
.build()
// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
.Builder()
.setSyncAcrossDevices(true)
.setAccountProfile(accountProfile)
.addRecommendationCluster(recommendationCluster1)
.addRecommendationCluster(recommendationCluster2)
.build()
When the service receives the request, the following actions occur within one
transaction:
- Existing `RecommendationsCluster` data from the developer partner is removed.
- Data from the request is parsed and stored in the updated `RecommendationsCluster`. In case of an error, the entire request is rejected and the existing state is maintained.
> [!NOTE]
> **Note:** Publish APIs are upsert operations, replacing existing content; update entities by republishing the entire cluster. Only publish recommendations for adult accounts. Avoid using delete APIs followed by publish, as the latter inherently replaces content.
### Cross-device sync
`SyncAcrossDevices` flag controls whether a user's recommendations cluster data
is shared with Google TV and available across their devices such as TV, phone,
tablets. In order for the recommendation to work, it must be set to true.
### Obtain consent
The media application must provide a clear setting to enable or disable
cross-device syncing. Explain the benefits to the user and store the user's
preference once and apply it in `publishRecommendations` Request accordingly. To
get the most out of cross-device feature, verify app obtains user
consent and enables `SyncAcrossDevices` to `true`.
### Delete the Engage data
To manually delete a user's data from the Google TV server before the standard
60-day retention period, use the `client.deleteClusters()` method. Upon
receiving the request, the service deletes all existing Engage
data for the account profile, or for the entire account.
The [`DeleteReason`](https://developer.android.com/reference/com/google/android/engage/service/DeleteReason) enum defines the reason for data deletion.
The following code removes recommendations on logout.
// If the user logs out from your media app, you must make the following call
// to remove recommendations data from the current Google TV device, otherwise,
// the recommendations data persists on the current Google TV device until 60
// days later.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(AccountProfile())
.setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
.build()
)
// If the user revokes the consent to share data with Google TV, you must make
// the following call to remove recommendations data from all current Google TV
// devices. Otherwise, the recommendations data persists until 60 days later.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(AccountProfile())
.setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
.build()
)
## Create entities
The SDK has defined different entities to represent each item type. Following
entities are supported for the Recommendation cluster:
1. [`MediaActionFeedEntity`](https://developer.android.com/reference/com/google/android/engage/video/datamodel/MediaActionFeedEntity)
2. [`MovieEntity`](https://developer.android.com/reference/com/google/android/engage/video/datamodel/MovieEntity)
3. [`TvShowEntity`](https://developer.android.com/reference/com/google/android/engage/video/datamodel/TvShowEntity)
4. [`LiveTvChannelEntity`](https://developer.android.com/reference/com/google/android/engage/video/datamodel/LiveTvChannelEntity)
5. [`LiveTvProgramEntity`](https://developer.android.com/reference/com/google/android/engage/video/datamodel/LiveTvProgramEntity)
### Provide descriptions
Provide a short description for each entity; this description will be displayed
when users hover over the entity, providing them with additional details.
### Call to action text
Provide an optional call to action text for each entity. This text will be
displayed to the user to encourage engagement.
### Tags
Optionally provide a list of tags for each entity. Tags can be used for
categorization and filtering.
### Platform specific playBack URIs
Create playback URIs for each supported platform: Android TV, Android, or iOS.
This allows the system to select the appropriate URI for video playback on the
respective platform.
In the rare case when the playback URIs are identical for all platforms,
repeat it for every platform.
// Required. Set this when you want recommended entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_TV)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
val playbackUriAndroid = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_IOS)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
.build()
val platformSpecificPlaybackUris =
Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)
// Provide appropriate rating for the system.
val contentRating = new RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
### Poster images
Poster images require a URI and pixel dimensions (height and width). Target
different form factors by providing multiple poster images, but verify all
images maintain a 16:9 aspect ratio and a minimum height of 200 pixels for
correct display of the "Recommendations" entity, especially within Google's
[Entertainment Space](https://support.google.com/entertainmentspace/answer/10346911). Images with a height less than 200
pixels may not be shown.
Image image1 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
.setImageHeightInPixel(300)
.setImageWidthInPixel(169)
.build()
Image image2 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
.setImageHeightInPixel(640)
.setImageWidthInPixel(360)
.build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
### Recommendation reason
Optionally provide a recommendation reason which can be used by Google
TV to construct reasons as to why to suggest a specific Movie or TV Show to
the user.
//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
.Builder()
.setNum(10) //any valid integer value
.build()
//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
.Builder()
.build()
//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
.Builder()
.build()
//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
.addSimilarWatchedTitleName("Movie or TV Show Title")
.addSimilarWatchedTitleName("Movie or TV Show Title")
.Builder()
.build()
//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
.Builder()
.build()
val watchAgain = RecommendationReasonWatchAgain
.Builder()
.build()
val fromUserWatchList = RecommendationReasonFromUserWatchlist
.Builder()
.build()
val userLikedOnPartner = RecommendationReasonUserLikedOnPartner
.Builder()
.setTitleName("Movie or TV Show Title")
.build()
val generic = RecommendationReasonGeneric.Builder().build()
### Display time window
If an entity should only be available for a limited time, set a custom
expiration time. Without an explicit expiration time, entities will
automatically expire and be erased after 60 days. So set an expiration time only
when the entities need to be expired sooner. Specify multiple such
availability windows.
val window1 = DisplayTimeWindow
.Builder()
.setStartTimeStampMillis(now()+ 1.days.toMillis())
.setEndTimeStampMillis(now()+ 30.days.toMillis())
val window2 = DisplayTimeWindow
.Builder()
.setEndTimeStampMillis(now()+ 30.days.toMillis())
val availabilityTimeWindows: List<DisplayTimeWindow> = listof(window1,window2)
### DataFeedElementId
If you have integrated your Media catalogue or Media action feed with Google TV,
you need not create separate entities for Movie or TV Show and instead you can
create a [`MediaActionFeedEntity`](https://developer.android.com/reference/com/google/android/engage/video/datamodel/MediaActionFeedEntity) which includes the
required field DataFeedElementId. This Id must be unique and must match with the
ID in Media Action Feed as it helps to identify ingested feed content and
perform media content lookups.
val id = "dataFeedElementId"
### `MovieEntity`
Here's an example of creating a `MovieEntity` with all the required fields:
val movieEntity = MovieEntity.Builder()
.setName("Movie name")
.setDescription("A sentence describing movie.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
// Suppose the duration is 2 hours, it is 72000000 in milliseconds
.setDurationMills(72000000)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
You can provide additional data such as genres, content ratings, release date,
recommendation reason and availability time windows, which may be used by Google
TV for enhanced displays or filtering purposes.
val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("pg-13").build();
val contentRatings = Arrays.asList(rating1);
//Suppose release date is 11-02-2025
val releaseDate = 1739233800000L
val movieEntity = MovieEntity.Builder()
...
.addGenres(genres)
.setReleaseDateEpochMillis(releaseDate)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.build()
### `TvShowEntity`
Here's an example of creating a `TvShowEntity` with all the required fields:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
.setCallToActionText("Watch Now")
.addTag("Drama")
.build();
Optionally provide additional data such as genres, content ratings,
recommendation reason, offer price, season count or availability time window,
which may be used by Google TV for enhanced displays or filtering purposes.
val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build();
val price = Price.Builder()
.setCurrentPrice("$14.99")
.setStrikethroughPrice("$16.99")
.build();
val contentRatings = Arrays.asList(rating1);
val seasonCount = 5;
val tvShowEntity = TvShowEntity.Builder()
...
.addGenres(genres)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.setSeasonCount(seasonCount)
.setPrice(price)
.build()
### `MediaActionFeedEntity`
Here's an example of creating an `MediaActionFeedEntity` with all the required
fields:
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
Optionally provide additional data such as description, recommendation reason
and display time window, which may be used by Google TV for enhanced displays or
filtering purposes.
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setName("Movie name or TV Show name")
.setDescription("A sentence describing an entity")
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addPosterImages(images)
.build()
### `LiveTvChannelEntity`
This represents a live TV channel. Here's an example of creating a
`LiveTvChannelEntity` with all the required fields:
val liveTvChannelEntity = LiveTvChannelEntity.Builder()
.setName("Channel Name")
// ID of the live TV channel
.setEntityId("https://www.example.com/channel/12345")
.setDescription("A sentence describing this live TV channel.")
// channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
.addPlatformSpecificPlaybackUri(channelPlaybackUris)
.addLogoImage(logoImage)
.setCallToActionText("Watch Now")
.addTag("News")
.build()
Optionally provide additional data such as content ratings or
recommendation reason.
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build()
val contentRatings = Arrays.asList(rating1)
val liveTvChannelEntity = LiveTvChannelEntity.Builder()
...
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner)
.build()
### `LiveTvProgramEntity`
This represents a live TV program card airing or scheduled to air on
a live TV channel. Here's an example of creating a `LiveTvProgramEntity`
with all the required fields:
val liveTvProgramEntity = LiveTvProgramEntity.Builder()
// First set the channel information
.setChannelName("Channel Name")
.setChannelId("https://www.example.com/channel/12345")
// channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
.addPlatformSpecificPlaybackUri(channelPlaybackUris)
.setChannelLogoImage(channelLogoImage)
// Then set the program or card specific information.
.setName("Program Name")
.setEntityId("https://www.example.com/schedule/123")
.setDescription("Program Description")
.addAvailabilityTimeWindow(
DisplayTimeWindow.Builder()
.setStartTimestampMillis(1756713600000L)// 2025-09-01T07:30:00+0000
.setEndTimestampMillis(1756715400000L))// 2025-09-01T08:00:00+0000
.addPosterImage(programImage)
.setCallToActionText("Watch Now")
.addTag("Sports")
.build()
Optionally provide additional data such as content ratings, genres, or
recommendation reason.
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build()
val contentRatings = Arrays.asList(rating1)
val genres = Arrays.asList("Action", "Science fiction")
val liveTvProgramEntity = LiveTvProgramEntity.Builder()
...
.addContentRatings(contentRatings)
.addGenres(genres)
.setRecommendationReason(topOnPartner)
.build()
> [!NOTE]
> **Note:** If the additional fields are provided directly within the entity, these values will be prioritized. The locale, if provided in the Account Profile, will be used to fetch the remaining entity metadata from Google's database in the language consistent with the request.

1064
.agents/skills/engage-sdk-integration/references/android/guide/playcore/engage/watch.md Normal file
View File

File diff suppressed because it is too large Load Diff

149
.agents/skills/engage-sdk-integration/references/clusters.md Normal file
View File

@@ -0,0 +1,149 @@
This file defines the structure of various clusters in the Engage SDK.
{
"clusters": {
"FeaturedCluster": {
"package": "com.google.android.engage.common.datamodel.FeaturedCluster",
"fields": {
"entities": {
"type": "List<Entity>",
"requirement": "Required",
"adder": "addEntity(Entity)",
"getter": "getEntities()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"ContinuationCluster": {
"package": "com.google.android.engage.common.datamodel.ContinuationCluster",
"fields": {
"syncAcrossDevices": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setSyncAcrossDevices(boolean)",
"getter": "getSyncAcrossDevices()"
},
"accountProfile": {
"type": "AccountProfile",
"requirement": "Optional",
"setter": "setAccountProfile(AccountProfile)",
"getter": "getAccountProfile()"
},
"entities": {
"type": "List<Entity>",
"requirement": "Required",
"adder": "addEntity(Entity)",
"getter": "getEntities()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"RecommendationCluster": {
"package": "com.google.android.engage.common.datamodel.RecommendationCluster",
"fields": {
"entities": {
"type": "List<Entity>",
"requirement": "Required",
"adder": "addEntity(Entity)",
"getter": "getEntities()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"subtitle": {
"type": "String",
"requirement": "Optional",
"setter": "setSubtitle(String)",
"getter": "getSubtitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"actionUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"recommendationClusterType": {
"type": "@RecommendationClusterType int",
"requirement": "Optional",
"setter": "setRecommendationClusterType(@RecommendationClusterType int)",
"getter": "getRecommendationClusterType()"
}
}
},
"SubscriptionCluster": {
"package": "com.google.android.engage.common.datamodel.SubscriptionCluster",
"fields": {
"accountProfile": {
"type": "AccountProfile",
"requirement": "Optional",
"setter": "setAccountProfile(AccountProfile)",
"getter": "getAccountProfile()"
},
"subscriptionEntities": {
"type": "List<SubscriptionEntity>",
"requirement": "Required",
"adder": "addSubscriptionEntity(SubscriptionEntity)",
"getter": "getSubscriptionEntities()"
}
}
},
"EngagementCluster": {
"package": "com.google.android.engage.common.datamodel.EngagementCluster",
"fields": {
"signInCardEntity": {
"type": "SignInCardEntity",
"requirement": "Required",
"setter": "setSignInCardEntity(SignInCardEntity)"
},
"userSettingsCardEntity": {
"type": "UserSettingsCardEntity",
"requirement": "Required",
"setter": "setUserSettingsCardEntity(UserSettingsCardEntity)"
}
}
}
}
}

519
.agents/skills/engage-sdk-integration/references/common.md Normal file
View File

@@ -0,0 +1,519 @@
This file defines common data models and entities used across the Engage SDK.
{
"entities": {
"Image": {
"package": "com.google.android.engage.common.datamodel.Image",
"fields": {
"imageUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setImageUri(Uri)",
"getter": "getImageUri()"
},
"height": {
"type": "Integer",
"requirement": "Optional"
},
"width": {
"type": "Integer",
"requirement": "Optional"
},
"accessibilityText": {
"type": "String",
"requirement": "Required",
"setter": "setAccessibilityText(String)",
"getter": "getAccessibilityText()"
},
"theme": {
"type": "ImageThemeEnum",
"requirement": "Optional"
},
"cropType": {
"type": "ImageCropTypeEnum",
"requirement": "Optional"
},
"imageHeightInPixel": {
"requirement": "Required",
"setter": "setImageHeightInPixel(int)",
"type": "Integer",
"getter": "getImageHeightInPixel()"
},
"imageWidthInPixel": {
"requirement": "Required",
"setter": "setImageWidthInPixel(int)",
"type": "Integer",
"getter": "getImageWidthInPixel()"
},
"imageTheme": {
"requirement": "Optional",
"setter": "setImageTheme(@ImageTheme int)",
"type": "@ImageTheme int",
"getter": "getImageTheme()"
},
"imageCropType": {
"requirement": "Optional",
"setter": "setImageCropType(@ImageCropType int)",
"type": "@ImageCropType int",
"getter": "getImageCropType()"
}
}
},
"Price": {
"package": "com.google.android.engage.common.datamodel.Price",
"fields": {
"currentPrice": {
"type": "String",
"requirement": "Required",
"setter": "setCurrentPrice(String)",
"getter": "getCurrentPrice()"
},
"strikethroughPrice": {
"type": "String",
"requirement": "Optional",
"setter": "setStrikethroughPrice(String)",
"getter": "getStrikethroughPrice()"
}
}
},
"Rating": {
"package": "com.google.android.engage.common.datamodel.Rating",
"fields": {
"ratingValue": {
"type": "Float",
"requirement": "Required"
},
"maxValue": {
"type": "Double",
"requirement": "Required",
"setter": "setMaxValue(double)",
"getter": "getMaxValue()"
},
"ratingCount": {
"type": "Integer",
"requirement": "Optional"
},
"ratingCountValue": {
"type": "String",
"requirement": "Optional"
},
"currentValue": {
"requirement": "Required",
"setter": "setCurrentValue(double)",
"type": "Double",
"getter": "getCurrentValue()"
},
"count": {
"requirement": "Optional",
"setter": "setCount(String)",
"type": "String",
"getter": "getCount()"
},
"countValue": {
"requirement": "Optional",
"setter": "setCountValue(long)",
"type": "Long",
"getter": "getCountValue()"
}
}
},
"DisplayTimeWindow": {
"package": "com.google.android.engage.common.datamodel.DisplayTimeWindow",
"fields": {
"startTimeMillis": {
"type": "Long",
"requirement": "Required"
},
"endTimeMillis": {
"type": "Long",
"requirement": "Required"
},
"startTimestampMillis": {
"requirement": "Optional",
"setter": "setStartTimestampMillis(long)",
"type": "Long",
"getter": "getStartTimestampMillis()"
},
"endTimestampMillis": {
"requirement": "Optional",
"setter": "setEndTimestampMillis(long)",
"type": "Long",
"getter": "getEndTimestampMillis()"
}
}
},
"AccountProfile": {
"package": "com.google.android.engage.common.datamodel.AccountProfile",
"fields": {
"accountId": {
"type": "@NonNull String",
"requirement": "Required",
"setter": "setAccountId(@NonNull String)",
"getter": "getAccountId()"
},
"profileId": {
"type": "@NonNull String",
"requirement": "Optional",
"setter": "setProfileId(@NonNull String)",
"getter": "getProfileId()"
},
"accountName": {
"type": "String",
"requirement": "Optional"
},
"profileImage": {
"type": "Image",
"requirement": "Optional"
},
"locale": {
"requirement": "Optional",
"setter": "setLocale(@NonNull String)",
"type": "@NonNull String",
"getter": "getLocale()"
}
}
},
"Address": {
"package": "com.google.android.engage.common.datamodel.Address",
"fields": {
"city": {
"type": "@NonNull String",
"requirement": "Required",
"setter": "setCity(@NonNull String)",
"getter": "getCity()"
},
"country": {
"type": "@NonNull String",
"requirement": "Required",
"setter": "setCountry(@NonNull String)",
"getter": "getCountry()"
},
"displayAddress": {
"type": "@NonNull String",
"requirement": "Required",
"setter": "setDisplayAddress(@NonNull String)",
"getter": "getDisplayAddress()"
},
"streetAddress": {
"type": "String",
"requirement": "Optional",
"setter": "setStreetAddress(String)",
"getter": "getStreetAddress()"
},
"state": {
"type": "String",
"requirement": "Optional",
"setter": "setState(String)",
"getter": "getState()"
},
"zipCode": {
"type": "String",
"requirement": "Optional",
"setter": "setZipCode(String)",
"getter": "getZipCode()"
},
"neighborhood": {
"type": "String",
"requirement": "Optional",
"setter": "setNeighborhood(String)",
"getter": "getNeighborhood()"
}
}
},
"Badge": {
"package": "com.google.android.engage.common.datamodel.Badge",
"fields": {
"text": {
"type": "String",
"requirement": "Optional",
"setter": "setText(String)",
"getter": "getText()"
},
"image": {
"type": "Image",
"requirement": "Optional",
"setter": "setImage(Image)",
"getter": "getImage()"
}
}
},
"LocalizedTimestamp": {
"package": "com.google.android.engage.common.datamodel.LocalizedTimestamp",
"fields": {
"timestamp": {
"type": "Instant",
"requirement": "Required",
"setter": "setTimestamp(Instant)",
"getter": "getTimestamp()"
},
"timezone": {
"type": "DateTimeZone",
"requirement": "Required",
"setter": "setTimezone(DateTimeZone)",
"getter": "getTimezone()"
}
}
},
"SignInCardEntity": {
"package": "com.google.android.engage.common.datamodel.SignInCardEntity",
"fields": {
"actionText": {
"type": "String",
"requirement": "Required",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"subtitle": {
"type": "String",
"requirement": "Optional",
"setter": "setSubtitle(String)",
"getter": "getSubtitle()"
},
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
}
}
},
"GenericFeaturedEntity": {
"package": "com.google.android.engage.common.datamodel.GenericFeaturedEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"contentCategories": {
"type": "List<@EligibleContentCategory int>",
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"adderAll": "addContentCategories(List<Integer>)"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"SubscriptionEntity": {
"package": "com.google.android.engage.common.datamodel.SubscriptionEntity",
"fields": {}
},
"UserSettingsCardEntity": {
"package": "com.google.android.engage.common.datamodel.UserSettingsCardEntity",
"fields": {
"actionText": {
"type": "String",
"requirement": "Required",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"subtitle": {
"type": "String",
"requirement": "Optional",
"setter": "setSubtitle(String)",
"getter": "getSubtitle()"
},
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
}
}
},
"ArticleEntity": {
"package": "com.google.android.engage.common.datamodel.ArticleEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"contentCategories": {
"type": "List<@EligibleContentCategory int>",
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"adderAll": "addContentCategories(List<Integer>)"
},
"progressPercentage": {
"type": "Integer",
"requirement": "Required",
"setter": "setProgressPercentage(int)",
"getter": "getProgressPercentage()",
"requiredFor": [
"ContinuationCluster"
]
},
"lastEngagementTimestampMillis": {
"type": "Long",
"requirement": "Required",
"setter": "setLastEngagementTimestampMillis(long)",
"getter": "getLastEngagementTimestampMillis()",
"requiredFor": [
"ContinuationCluster"
]
},
"source": {
"type": "Badge",
"requirement": "Optional",
"setter": "setSource(Badge)",
"getter": "getSource()"
},
"lastContentPublishTimestampMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastContentPublishTimestampMillis(Long)",
"getter": "getLastContentPublishTimestampMillis()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
}
},
"intents": {
"ACTION_PUBLISH_RECOMMENDATION": "com.google.android.engage.action.PUBLISH_RECOMMENDATION",
"ACTION_PUBLISH_FEATURED": "com.google.android.engage.action.PUBLISH_FEATURED",
"ACTION_PUBLISH_CONTINUATION": "com.google.android.engage.action.PUBLISH_CONTINUATION"
},
"imports": [
"com.google.android.engage.service.AppEngagePublishClient",
"com.google.android.engage.service.AppEngageErrorCode",
"com.google.android.engage.service.AppEngageException",
"com.google.android.engage.service.AppEngagePublishStatusCode"
]
}

484
.agents/skills/engage-sdk-integration/references/patterns.md Normal file
View File

@@ -0,0 +1,484 @@
## EngageBroadcastReceiver
Setting up the `BroadcastReceiver` correctly requires **both** static and
dynamic registration. Static registration allows the app to receive broadcasts
even when it is not 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 (AndroidManifest.xml)
Add the `<receiver>` tag inside the `<application>` block in
`AndroidManifest.xml`
```kotlin
<!-- 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.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.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()
}
// Check if engage service is available before publishing.
val isAvailable = client.isServiceAvailable.await()
// If the service is not available, do not attempt to publish and indicate failure.
if (!isAvailable) {
return Result.failure()
}
val publishType = inputData.getString(Constants.PUBLISH_TYPE_KEY)
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 />
## Dependency Specifications (libs.versions.toml)
This skill specifies all dependencies following in `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.5.12"
engage-tv = "1.0.6"
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" }
## TV Integrations
The following patterns and configurations are specific to Android TV
integrations.
### AndroidManifest.xml (TV)
```kotlin
<!-- 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 />

231
.agents/skills/engage-sdk-integration/references/requests.md Normal file
View File

@@ -0,0 +1,231 @@
This file defines the request structures for publishing various data models in
the Engage SDK.
{
"PublishRecommendationClustersRequest": {
"package": "com.google.android.engage.service.PublishRecommendationClustersRequest",
"fields": {
"recommendationClusters": {
"type": "List<RecommendationCluster>",
"requirement": "Required",
"adder": "addRecommendationCluster(RecommendationCluster)",
"getter": "getRecommendationClusters()"
},
"accountProfile": {
"type": "@NonNull AccountProfile",
"requirement": "Optional",
"setter": "setAccountProfile(@NonNull AccountProfile)",
"getter": "getAccountProfile()"
},
"syncAcrossDevices": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setSyncAcrossDevices(boolean)",
"getter": "getSyncAcrossDevices()"
}
}
},
"PublishFeaturedClusterRequest": {
"package": "com.google.android.engage.service.PublishFeaturedClusterRequest",
"fields": {
"featuredCluster": {
"type": "FeaturedCluster",
"requirement": "Required",
"setter": "setFeaturedCluster(FeaturedCluster)",
"getter": "getFeaturedCluster()"
}
}
},
"DeleteClustersRequest": {
"package": "com.google.android.engage.service.DeleteClustersRequest",
"fields": {
"clusterTypes": {
"type": "List<@ClusterType int>",
"requirement": "Optional",
"adder": "addClusterType(@ClusterType int)"
},
"deleteReason": {
"type": "@DeleteReason int",
"requirement": "Optional",
"setter": "setDeleteReason(@DeleteReason int)",
"getter": "getDeleteReason()"
},
"accountProfile": {
"requirement": "Optional",
"setter": "setAccountProfile(AccountProfile)",
"type": "AccountProfile",
"getter": "getAccountProfile()"
},
"syncAcrossDevices": {
"requirement": "Optional",
"setter": "setSyncAcrossDevices(boolean)",
"type": "Boolean",
"getter": "getSyncAcrossDevices()"
}
}
},
"PublishContinuationClusterRequest": {
"package": "com.google.android.engage.service.PublishContinuationClusterRequest",
"fields": {
"continuationCluster": {
"type": "ContinuationCluster",
"requirement": "Required",
"setter": "setContinuationCluster(ContinuationCluster)",
"getter": "getContinuationCluster()"
}
}
},
"PublishStatusRequest": {
"package": "com.google.android.engage.service.PublishStatusRequest",
"fields": {
"statusCode": {
"type": "@AppEngagePublishStatusCode int",
"requirement": "Required",
"setter": "setStatusCode(@AppEngagePublishStatusCode int)",
"getter": "getStatusCode()"
}
}
},
"PublishSubscriptionRequest": {
"package": "com.google.android.engage.service.PublishSubscriptionRequest",
"fields": {
"subscriptionClusters": {
"type": "List<SubscriptionCluster>",
"requirement": "Required"
},
"accountProfile": {
"type": "AccountProfile",
"requirement": "Required",
"setter": "setAccountProfile(AccountProfile)",
"getter": "getAccountProfile()"
},
"subscription": {
"requirement": "Required",
"setter": "setSubscription(SubscriptionEntity)",
"type": "SubscriptionEntity",
"getter": "getSubscription()"
}
}
},
"PublishUserAccountManagementRequest": {
"package": "com.google.android.engage.service.PublishUserAccountManagementRequest",
"fields": {
"actionUri": {
"type": "Uri",
"requirement": "Required"
},
"signInCardEntity": {
"type": "SignInCardEntity",
"requirement": "Required",
"setter": "setSignInCardEntity(SignInCardEntity)"
},
"userSettingsCardEntity": {
"requirement": "Required",
"setter": "setUserSettingsCardEntity(UserSettingsCardEntity)",
"type": "UserSettingsCardEntity"
}
}
},
"PublishShoppingCartClusterRequest": {
"package": "com.google.android.engage.shopping.service.PublishShoppingCartClusterRequest",
"fields": {
"shoppingCart": {
"requirement": "Required",
"setter": "setShoppingCart(ShoppingCart)",
"type": "ShoppingCart",
"getter": "getShoppingCart()"
}
}
},
"PublishShoppingListsRequest": {
"package": "com.google.android.engage.shopping.service.PublishShoppingListsRequest",
"fields": {
"shoppingLists": {
"type": "List<ShoppingList>",
"requirement": "Optional",
"adder": "addShoppingList(ShoppingList)",
"getter": "getShoppingLists()",
"adderAll": "addShoppingLists(List<ShoppingList>)"
}
}
},
"PublishShoppingOrderTrackingClusterRequest": {
"package": "com.google.android.engage.shopping.service.PublishShoppingOrderTrackingClusterRequest",
"fields": {
"shoppingOrderTrackingCluster": {
"type": "ShoppingOrderTrackingCluster",
"requirement": "Required",
"setter": "setShoppingOrderTrackingCluster(ShoppingOrderTrackingCluster)",
"getter": "getShoppingOrderTrackingCluster()"
}
}
},
"PublishShoppingReorderClusterRequest": {
"package": "com.google.android.engage.shopping.service.PublishShoppingReorderClusterRequest",
"fields": {
"reorderCluster": {
"type": "ShoppingReorderCluster",
"requirement": "Required",
"setter": "setReorderCluster(ShoppingReorderCluster)",
"getter": "getReorderCluster()"
}
}
},
"PublishFoodShoppingCartsRequest": {
"package": "com.google.android.engage.food.service.PublishFoodShoppingCartsRequest",
"fields": {
"foodShoppingCarts": {
"type": "List<FoodShoppingCart>",
"requirement": "Optional",
"adder": "addFoodShoppingCart(FoodShoppingCart)",
"getter": "getFoodShoppingCarts()",
"adderAll": "addFoodShoppingCarts(List<FoodShoppingCart>)"
}
}
},
"PublishFoodShoppingListsRequest": {
"package": "com.google.android.engage.food.service.PublishFoodShoppingListsRequest",
"fields": {
"foodShoppingLists": {
"type": "List<FoodShoppingList>",
"requirement": "Optional",
"adder": "addFoodShoppingList(FoodShoppingList)",
"getter": "getFoodShoppingLists()",
"adderAll": "addFoodShoppingLists(List<FoodShoppingList>)"
}
}
},
"PublishReorderClusterRequest": {
"package": "com.google.android.engage.food.service.PublishReorderClusterRequest",
"fields": {
"reorderCluster": {
"requirement": "Required",
"setter": "setReorderCluster(FoodReorderCluster)",
"type": "FoodReorderCluster",
"getter": "getReorderCluster()"
}
}
},
"PublishContinueSearchClusterRequest": {
"package": "com.google.android.engage.travel.service.PublishContinueSearchClusterRequest",
"fields": {
"continueSearchCluster": {
"type": "ContinueSearchCluster",
"requirement": "Required",
"setter": "setContinueSearchCluster(ContinueSearchCluster)",
"getter": "getContinueSearchCluster()"
}
}
},
"PublishReservationClusterRequest": {
"package": "com.google.android.engage.travel.service.PublishReservationClusterRequest",
"fields": {
"reservationCluster": {
"type": "ReservationCluster",
"requirement": "Required",
"setter": "setReservationCluster(ReservationCluster)",
"getter": "getReservationCluster()"
}
}
}
}

509
.agents/skills/engage-sdk-integration/references/schemas/food.md Normal file
View File

@@ -0,0 +1,509 @@
This file defines the schema for the FOOD vertical in the Engage SDK.
{
"client": "com.google.android.engage.food.service.AppEngageFoodClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED",
"TYPE_FOOD_SHOPPING_CART",
"TYPE_FOOD_SHOPPING_LIST",
"TYPE_FOOD_REORDER"
],
"entities": {
"ProductEntity": {
"package": "com.google.android.engage.food.datamodel.ProductEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()",
"requiredFor": [
"Required if strikethrough price is provided",
"Mutually required with other rating fields"
]
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"callout": {
"type": "String",
"requirement": "Optional",
"setter": "setCallout(String)",
"getter": "getCallout()"
},
"calloutFinePrint": {
"type": "String",
"requirement": "Optional",
"setter": "setCalloutFinePrint(String)",
"getter": "getCalloutFinePrint()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
}
}
},
"StoreEntity": {
"package": "com.google.android.engage.food.datamodel.StoreEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()",
"requiredFor": [
"Mutually required with other rating fields"
]
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"location": {
"type": "String",
"requirement": "Optional",
"setter": "setLocation(String)",
"getter": "getLocation()"
},
"category": {
"type": "String",
"requirement": "Optional",
"setter": "setCategory(String)",
"getter": "getCategory()"
},
"callout": {
"type": "String",
"requirement": "Optional",
"setter": "setCallout(String)",
"getter": "getCallout()"
},
"calloutFinePrint": {
"type": "String",
"requirement": "Optional",
"setter": "setCalloutFinePrint(String)",
"getter": "getCalloutFinePrint()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"RestaurantReservationEntity": {
"package": "com.google.android.engage.food.datamodel.RestaurantReservationEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"location": {
"type": "Address",
"requirement": "Required",
"setter": "setLocation(Address)",
"getter": "getLocation()"
},
"reservationStartTime": {
"type": "Long",
"requirement": "Required",
"setter": "setReservationStartTime(Long)",
"getter": "getReservationStartTime()"
},
"localizedReservationStartTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedReservationStartTime(LocalizedTimestamp)",
"getter": "getLocalizedReservationStartTime()"
},
"tableSize": {
"type": "Integer",
"requirement": "Optional",
"setter": "setTableSize(Integer)",
"getter": "getTableSize()"
},
"reservationId": {
"type": "String",
"requirement": "Optional",
"setter": "setReservationId(String)",
"getter": "getReservationId()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"RecipeEntity": {
"package": "com.google.android.engage.food.datamodel.RecipeEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()",
"requiredFor": [
"Mutually required with other rating fields"
]
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"author": {
"type": "String",
"requirement": "Optional",
"setter": "setAuthor(String)",
"getter": "getAuthor()"
},
"category": {
"type": "String",
"requirement": "Optional",
"setter": "setCategory(String)",
"getter": "getCategory()"
},
"callout": {
"type": "String",
"requirement": "Optional",
"setter": "setCallout(String)",
"getter": "getCallout()"
},
"cookTime": {
"type": "String",
"requirement": "Optional",
"setter": "setCookTime(String)",
"getter": "getCookTime()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishFeaturedCluster": "PublishFeaturedClusterRequest",
"publishFoodShoppingCarts": "PublishFoodShoppingCartsRequest",
"publishReorderCluster": "PublishReorderClusterRequest",
"publishFoodShoppingLists": "PublishFoodShoppingListsRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"deleteFoodShoppingCartCluster": "DeleteClustersRequest",
"deleteFoodShoppingListCluster": "DeleteClustersRequest",
"deleteReorderCluster": "DeleteClustersRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest",
"deleteFeaturedCluster": "DeleteClustersRequest",
"deleteUserManagementCluster": "DeleteClustersRequest"
},
"clusters": {
"FoodReorderCluster": {
"package": "com.google.android.engage.food.datamodel.FoodReorderCluster",
"fields": {
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"itemLabels": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addItemLabel(String)",
"getter": "getItemLabels()",
"adderAll": "addItemLabels(List<String>)"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(int)",
"getter": "getNumberOfItems()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"FoodShoppingList": {
"package": "com.google.android.engage.food.datamodel.FoodShoppingList",
"fields": {
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"itemLabels": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addItemLabel(String)",
"getter": "getItemLabels()",
"adderAll": "addItemLabels(List<String>)"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(int)",
"getter": "getNumberOfItems()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"lastUserInteractionTimestampMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastUserInteractionTimestampMillis(long)",
"getter": "getLastUserInteractionTimestampMillis()"
}
}
},
"FoodShoppingCart": {
"package": "com.google.android.engage.food.datamodel.FoodShoppingCart",
"fields": {
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"itemLabels": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addItemLabel(String)",
"getter": "getItemLabels()",
"adderAll": "addItemLabels(List<String>)"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(int)",
"getter": "getNumberOfItems()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"lastUserInteractionTimestampMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastUserInteractionTimestampMillis(long)",
"getter": "getLastUserInteractionTimestampMillis()"
}
}
}
},
"intents": {
"ACTION_PUBLISH_FOOD_SHOPPING_CART": "com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART",
"ACTION_PUBLISH_FOOD_SHOPPING_LIST": "com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST",
"ACTION_PUBLISH_REORDER_CLUSTER": "com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER"
}
}

842
.agents/skills/engage-sdk-integration/references/schemas/listen.md Normal file
View File

@@ -0,0 +1,842 @@
This file defines the schema for the LISTEN vertical in the Engage SDK.
{
"client": "com.google.android.engage.service.AppEngagePublishClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED",
"TYPE_CONTINUATION"
],
"entities": {
"MusicAlbumEntity": {
"package": "com.google.android.engage.audio.datamodel.MusicAlbumEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"songsCount": {
"type": "Integer",
"requirement": "Optional",
"setter": "setSongsCount(int)",
"getter": "getSongsCount()"
},
"releaseDateEpochMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setReleaseDateEpochMillis(long)",
"getter": "getReleaseDateEpochMillis()"
},
"durationMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setDurationMillis(long)",
"getter": "getDurationMillis()"
},
"genres": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addGenre(String)",
"getter": "getGenres()",
"adderAll": "addGenres(List<String>)"
},
"musicLabels": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addMusicLabel(String)",
"getter": "getMusicLabels()",
"adderAll": "addMusicLabels(List<String>)"
},
"artists": {
"type": "List<String>",
"requirement": "Required",
"adder": "addArtist(String)",
"getter": "getArtists()",
"adderAll": "addArtists(List<String>)"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"explicitContent": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setExplicitContent(boolean)",
"getter": "isExplicitContent()"
},
"musicAlbumType": {
"type": "@MusicAlbumType int",
"requirement": "Optional",
"setter": "setMusicAlbumType(@MusicAlbumType int)",
"getter": "getMusicAlbumType()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()"
}
}
},
"MusicTrackEntity": {
"package": "com.google.android.engage.audio.datamodel.MusicTrackEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"durationMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setDurationMillis(long)",
"getter": "getDurationMillis()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"album": {
"type": "String",
"requirement": "Optional",
"setter": "setAlbum(String)",
"getter": "getAlbum()"
},
"artists": {
"type": "List<String>",
"requirement": "Required",
"adder": "addArtist(String)",
"getter": "getArtists()",
"adderAll": "addArtists(List<String>)"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"explicitContent": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setExplicitContent(boolean)",
"getter": "isExplicitContent()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()"
}
}
},
"PodcastEpisodeEntity": {
"package": "com.google.android.engage.audio.datamodel.PodcastEpisodeEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"episodeIndex": {
"type": "Integer",
"requirement": "Optional",
"setter": "setEpisodeIndex(int)",
"getter": "getEpisodeIndex()"
},
"podcastSeriesTitle": {
"type": "String",
"requirement": "Required",
"setter": "setPodcastSeriesTitle(String)",
"getter": "getPodcastSeriesTitle()"
},
"productionName": {
"type": "String",
"requirement": "Required",
"setter": "setProductionName(String)",
"getter": "getProductionName()"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"durationMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setDurationMillis(long)",
"getter": "getDurationMillis()"
},
"publishDateEpochMillis": {
"type": "Long",
"requirement": "Required",
"setter": "setPublishDateEpochMillis(long)",
"getter": "getPublishDateEpochMillis()"
},
"genres": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addGenre(String)",
"getter": "getGenres()",
"adderAll": "addGenres(List<String>)"
},
"hosts": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addHost(String)",
"getter": "getHosts()",
"adderAll": "addHosts(List<String>)"
},
"explicitContent": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setExplicitContent(boolean)",
"getter": "isExplicitContent()"
},
"listenNextType": {
"type": "Integer",
"requirement": "Optional",
"setter": "setListenNextType(int)",
"getter": "getListenNextType()"
},
"videoPodcast": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setVideoPodcast(boolean)",
"getter": "isVideoPodcast()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()"
}
}
},
"MusicVideoEntity": {
"package": "com.google.android.engage.audio.datamodel.MusicVideoEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"durationMillis": {
"type": "Long",
"requirement": "Required",
"setter": "setDurationMillis(long)",
"getter": "getDurationMillis()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"viewCount": {
"type": "String",
"requirement": "Optional",
"setter": "setViewCount(String)",
"getter": "getViewCount()"
},
"artists": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addArtist(String)",
"getter": "getArtists()",
"adderAll": "addArtists(List<String>)"
},
"contentRatings": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addContentRating(String)",
"getter": "getContentRatings()",
"adderAll": "addContentRatings(List<String>)"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"explicitContent": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setExplicitContent(boolean)",
"getter": "isExplicitContent()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()"
}
}
},
"LiveRadioStationEntity": {
"package": "com.google.android.engage.audio.datamodel.LiveRadioStationEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"radioFrequencyId": {
"type": "String",
"requirement": "Optional",
"setter": "setRadioFrequencyId(String)",
"getter": "getRadioFrequencyId()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"showTitle": {
"type": "String",
"requirement": "Optional",
"setter": "setShowTitle(String)",
"getter": "getShowTitle()"
},
"hosts": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addHost(String)",
"getter": "getHosts()",
"adderAll": "addHosts(List<String>)"
}
}
},
"GenericAudioEntity": {
"package": "com.google.android.engage.audio.datamodel.GenericAudioEntity",
"fields": {
"entityId": {
"requirement": "Optional",
"setter": "setEntityId(String)",
"type": "String",
"getter": "getEntityId()"
},
"name": {
"requirement": "Required",
"setter": "setName(String)",
"type": "String",
"getter": "getName()"
},
"posterImages": {
"requirement": "Required",
"adder": "addPosterImage(Image)",
"type": "List<Image>",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"requirement": "Required",
"setter": "setActionUri(Uri)",
"type": "Uri",
"getter": "getActionUri()"
},
"downloadedOnDevice": {
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"type": "Boolean",
"getter": "isDownloadedOnDevice()"
},
"explicitContent": {
"requirement": "Required",
"setter": "setExplicitContent(boolean)",
"type": "Boolean",
"getter": "isExplicitContent()"
},
"progressPercentComplete": {
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"type": "Integer",
"getter": "getProgressPercentComplete()"
},
"lastEngagementTimeMillis": {
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"type": "Long",
"getter": "getLastEngagementTimeMillis()"
},
"listenNextType": {
"requirement": "Optional",
"setter": "setListenNextType(@ListenNextType int)",
"type": "@ListenNextType int",
"getter": "getListenNextType()"
},
"price": {
"requirement": "Optional",
"setter": "setPrice(Price)",
"type": "Price",
"getter": "getPrice()"
},
"rating": {
"requirement": "Optional",
"setter": "setRating(Rating)",
"type": "Rating",
"getter": "getRating()"
},
"callout": {
"requirement": "Optional",
"setter": "setCallout(String)",
"type": "String",
"getter": "getCallout()"
},
"calloutFinePrint": {
"requirement": "Optional",
"setter": "setCalloutFinePrint(String)",
"type": "String",
"getter": "getCalloutFinePrint()"
},
"displayTimeWindows": {
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"type": "List<DisplayTimeWindow>",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"type": "List<List<DisplayTimeWindow>>",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"isBook": {
"requirement": "Optional",
"setter": "setIsBook(boolean)",
"type": "Boolean",
"getter": "isBook()"
},
"isTalk": {
"requirement": "Optional",
"setter": "setIsTalk(Boolean)",
"type": "Boolean",
"getter": "isTalk()"
},
"isVideoSupported": {
"requirement": "Optional",
"setter": "setIsVideoSupported(Boolean)",
"type": "Boolean",
"getter": "isVideoSupported()"
},
"isArtist": {
"requirement": "Optional",
"setter": "setIsArtist(Boolean)",
"type": "Boolean",
"getter": "isArtist()"
},
"subtitles": {
"requirement": "Optional",
"adder": "addSubtitle(String)",
"type": "List<String>",
"adderAll": "addSubtitles(List<String>)"
}
}
},
"PodcastSeriesEntity": {
"package": "com.google.android.engage.audio.datamodel.PodcastSeriesEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"episodeCount": {
"type": "Integer",
"requirement": "Optional",
"setter": "setEpisodeCount(int)",
"getter": "getEpisodeCount()"
},
"productionName": {
"type": "String",
"requirement": "Optional",
"setter": "setProductionName(String)",
"getter": "getProductionName()"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"genres": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addGenre(String)",
"getter": "getGenres()",
"adderAll": "addGenres(List<String>)"
},
"hosts": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addHost(String)",
"getter": "getHosts()",
"adderAll": "addHosts(List<String>)"
},
"explicitContent": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setExplicitContent(boolean)",
"getter": "isExplicitContent()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
}
}
},
"MusicArtistEntity": {
"package": "com.google.android.engage.audio.datamodel.MusicArtistEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
}
}
},
"PlaylistEntity": {
"package": "com.google.android.engage.audio.datamodel.PlaylistEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"playBackUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setPlayBackUri(Uri)",
"getter": "getPlayBackUri()"
},
"songsCount": {
"type": "Integer",
"requirement": "Required",
"setter": "setSongsCount(int)",
"getter": "getSongsCount()"
},
"durationMillis": {
"type": "Long",
"requirement": "Required",
"setter": "setDurationMillis(long)",
"getter": "getDurationMillis()"
},
"infoPageUri": {
"type": "Uri",
"requirement": "Optional",
"setter": "setInfoPageUri(Uri)",
"getter": "getInfoPageUri()"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"explicitContent": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setExplicitContent(boolean)",
"getter": "isExplicitContent()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()"
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishFeaturedCluster": "PublishFeaturedClusterRequest",
"publishContinuationCluster": "PublishContinuationClusterRequest",
"publishSubscription": "PublishSubscriptionRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest",
"deleteFeaturedCluster": "DeleteClustersRequest",
"deleteContinuationCluster": "DeleteClustersRequest",
"deleteSubscription": "DeleteClustersRequest",
"deleteUserManagementCluster": "DeleteClustersRequest"
},
"intents": {}
}

220
.agents/skills/engage-sdk-integration/references/schemas/other.md Normal file
View File

@@ -0,0 +1,220 @@
This file defines the schema for the OTHER vertical in the Engage SDK.
{
"client": "com.google.android.engage.service.AppEngagePublishClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED"
],
"entities": {
"ArticleEntity": {
"package": "com.google.android.engage.common.datamodel.ArticleEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitleList": {
"type": "List<String>",
"requirement": "Optional"
},
"badgeList": {
"type": "List<Badge>",
"requirement": "Optional"
},
"contentCategoryList": {
"type": "List<Integer>",
"requirement": "Optional"
},
"lastEngagementTime": {
"type": "Long",
"requirement": "Optional",
"requiredFor": [
"ContinuationCluster"
]
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"actionUri": {
"requirement": "Required",
"setter": "setActionUri(Uri)",
"type": "Uri",
"getter": "getActionUri()"
},
"subtitles": {
"requirement": "Optional",
"adder": "addSubtitle(String)",
"type": "List<String>",
"adderAll": "addSubtitles(List<String>)"
},
"badges": {
"requirement": "Optional",
"adder": "addBadge(Badge)",
"type": "List<Badge>",
"adderAll": "addBadges(List<Badge>)"
},
"contentCategories": {
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"type": "List<@EligibleContentCategory int>",
"adderAll": "addContentCategories(List<Integer>)"
},
"progressPercentage": {
"requirement": "Required",
"setter": "setProgressPercentage(int)",
"type": "Integer",
"getter": "getProgressPercentage()",
"requiredFor": [
"ContinuationCluster"
]
},
"lastEngagementTimestampMillis": {
"requirement": "Required",
"setter": "setLastEngagementTimestampMillis(long)",
"type": "Long",
"getter": "getLastEngagementTimestampMillis()"
},
"source": {
"requirement": "Optional",
"setter": "setSource(Badge)",
"type": "Badge",
"getter": "getSource()"
},
"lastContentPublishTimestampMillis": {
"requirement": "Optional",
"setter": "setLastContentPublishTimestampMillis(Long)",
"type": "Long",
"getter": "getLastContentPublishTimestampMillis()"
},
"allDisplayTimeWindows": {
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"type": "List<List<DisplayTimeWindow>>",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"GenericFeaturedEntity": {
"package": "com.google.android.engage.common.datamodel.GenericFeaturedEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitleList": {
"type": "List<String>",
"requirement": "Optional"
},
"badgeList": {
"type": "List<Badge>",
"requirement": "Optional"
},
"contentCategoryList": {
"type": "List<Integer>",
"requirement": "Optional"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"subtitles": {
"requirement": "Optional",
"adder": "addSubtitle(String)",
"type": "List<String>",
"adderAll": "addSubtitles(List<String>)"
},
"badges": {
"requirement": "Optional",
"adder": "addBadge(Badge)",
"type": "List<Badge>",
"adderAll": "addBadges(List<Badge>)"
},
"contentCategories": {
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"type": "List<@EligibleContentCategory int>",
"adderAll": "addContentCategories(List<Integer>)"
},
"allDisplayTimeWindows": {
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"type": "List<List<DisplayTimeWindow>>",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishFeaturedCluster": "PublishFeaturedClusterRequest",
"publishContinuationCluster": "PublishContinuationClusterRequest",
"publishSubscription": "PublishSubscriptionRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest",
"deleteFeaturedCluster": "DeleteClustersRequest",
"deleteContinuationCluster": "DeleteClustersRequest",
"deleteSubscription": "DeleteClustersRequest",
"deleteUserManagementCluster": "DeleteClustersRequest"
},
"intents": {}
}

412
.agents/skills/engage-sdk-integration/references/schemas/read.md Normal file
View File

@@ -0,0 +1,412 @@
This file defines the schema for the READ vertical in the Engage SDK.
{
"client": "com.google.android.engage.service.AppEngagePublishClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED",
"TYPE_CONTINUATION"
],
"entities": {
"EbookEntity": {
"package": "com.google.android.engage.books.datamodel.EbookEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"authors": {
"type": "List<String>",
"requirement": "Required",
"adder": "addAuthor(String)",
"getter": "getAuthors()",
"adderAll": "addAuthors(List<String>)"
},
"publishDateEpochMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setPublishDateEpochMillis(long)",
"getter": "getPublishDateEpochMillis()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"pageCount": {
"type": "Integer",
"requirement": "Optional",
"setter": "setPageCount(int)",
"getter": "getPageCount()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()"
},
"genres": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addGenre(String)",
"getter": "getGenres()",
"adderAll": "addGenres(List<String>)"
},
"seriesName": {
"type": "String",
"requirement": "Optional",
"setter": "setSeriesName(String)",
"getter": "getSeriesName()"
},
"seriesUnitIndex": {
"type": "Integer",
"requirement": "Optional",
"setter": "setSeriesUnitIndex(Integer)",
"getter": "getSeriesUnitIndex()"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()",
"requiredFor": [
"ContinuationCluster"
]
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()",
"requiredFor": [
"ContinuationCluster"
]
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()"
},
"availability": {
"type": "@ContentAvailability int",
"requirement": "Optional",
"setter": "setAvailability(@ContentAvailability int)",
"getter": "getAvailability()"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"continueBookType": {
"type": "Integer",
"requirement": "Optional",
"setter": "setContinueBookType(int)",
"getter": "getContinueBookType()",
"requiredFor": [
"ContinuationCluster"
]
}
}
},
"BookSeriesEntity": {
"package": "com.google.android.engage.books.datamodel.BookSeriesEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"bookCount": {
"type": "Integer",
"requirement": "Required",
"setter": "setBookCount(int)",
"getter": "getBookCount()"
},
"authors": {
"type": "List<String>",
"requirement": "Required",
"adder": "addAuthor(String)",
"getter": "getAuthors()",
"adderAll": "addAuthors(List<String>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"genres": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addGenre(String)",
"getter": "getGenres()",
"adderAll": "addGenres(List<String>)"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()",
"requiredFor": [
"ContinuationCluster"
]
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()",
"requiredFor": [
"ContinuationCluster"
]
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()"
},
"availability": {
"type": "@ContentAvailability int",
"requirement": "Optional",
"setter": "setAvailability(@ContentAvailability int)",
"getter": "getAvailability()"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"continueBookType": {
"type": "Integer",
"requirement": "Optional",
"setter": "setContinueBookType(int)",
"getter": "getContinueBookType()",
"requiredFor": [
"ContinuationCluster"
]
}
}
},
"AudiobookEntity": {
"package": "com.google.android.engage.books.datamodel.AudiobookEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"name": {
"type": "String",
"requirement": "Required",
"setter": "setName(String)",
"getter": "getName()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()"
},
"availability": {
"type": "@ContentAvailability int",
"requirement": "Optional",
"setter": "setAvailability(@ContentAvailability int)",
"getter": "getAvailability()"
},
"downloadedOnDevice": {
"type": "Boolean",
"requirement": "Optional",
"setter": "setDownloadedOnDevice(boolean)",
"getter": "isDownloadedOnDevice()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"authors": {
"type": "List<String>",
"requirement": "Required",
"adder": "addAuthor(String)",
"getter": "getAuthors()",
"adderAll": "addAuthors(List<String>)"
},
"narrators": {
"type": "List<String>",
"requirement": "Required",
"adder": "addNarrator(String)",
"getter": "getNarrators()",
"adderAll": "addNarrators(List<String>)"
},
"publishDateEpochMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setPublishDateEpochMillis(long)",
"getter": "getPublishDateEpochMillis()"
},
"durationMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setDurationMillis(long)",
"getter": "getDurationMillis()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()"
},
"seriesName": {
"type": "String",
"requirement": "Optional",
"setter": "setSeriesName(String)",
"getter": "getSeriesName()"
},
"seriesUnitIndex": {
"type": "Integer",
"requirement": "Optional",
"setter": "setSeriesUnitIndex(Integer)",
"getter": "getSeriesUnitIndex()"
},
"genres": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addGenre(String)",
"getter": "getGenres()",
"adderAll": "addGenres(List<String>)"
},
"lastEngagementTimeMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastEngagementTimeMillis(long)",
"getter": "getLastEngagementTimeMillis()"
},
"progressPercentComplete": {
"type": "Integer",
"requirement": "Optional",
"setter": "setProgressPercentComplete(int)",
"getter": "getProgressPercentComplete()"
},
"continueBookType": {
"type": "Integer",
"requirement": "Optional",
"setter": "setContinueBookType(int)",
"getter": "getContinueBookType()"
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishFeaturedCluster": "PublishFeaturedClusterRequest",
"publishContinuationCluster": "PublishContinuationClusterRequest",
"publishSubscription": "PublishSubscriptionRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest",
"deleteFeaturedCluster": "DeleteClustersRequest",
"deleteContinuationCluster": "DeleteClustersRequest",
"deleteSubscription": "DeleteClustersRequest",
"deleteUserManagementCluster": "DeleteClustersRequest"
},
"intents": {}
}

357
.agents/skills/engage-sdk-integration/references/schemas/shopping.md Normal file
View File

@@ -0,0 +1,357 @@
This file defines the schema for the SHOPPING vertical in the Engage SDK.
{
"client": "com.google.android.engage.shopping.service.AppEngageShoppingClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED",
"TYPE_SHOPPING_CART",
"TYPE_SHOPPING_LIST",
"TYPE_SHOPPING_REORDER",
"TYPE_SHOPPING_ORDER_TRACKING"
],
"entities": {
"ShoppingEntity": {
"package": "com.google.android.engage.shopping.datamodel.ShoppingEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"callout": {
"type": "String",
"requirement": "Optional",
"setter": "setCallout(String)",
"getter": "getCallout()"
},
"calloutFinePrint": {
"type": "String",
"requirement": "Optional",
"setter": "setCalloutFinePrint(String)",
"getter": "getCalloutFinePrint()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()",
"requiredFor": [
"Required if strikethrough price is provided",
"Mutually required with other rating fields"
]
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishFeaturedCluster": "PublishFeaturedClusterRequest",
"publishShoppingCart": "PublishShoppingCartClusterRequest",
"publishShoppingLists": "PublishShoppingListsRequest",
"publishShoppingReorderCluster": "PublishShoppingReorderClusterRequest",
"publishShoppingOrderTrackingCluster": "PublishShoppingOrderTrackingClusterRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"deleteShoppingCartCluster": "DeleteClustersRequest",
"deleteShoppingListCluster": "DeleteClustersRequest",
"deleteReorderCluster": "DeleteClustersRequest",
"deleteShoppingOrderTrackingCluster": "DeleteClustersRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest",
"deleteFeaturedCluster": "DeleteClustersRequest",
"deleteUserManagementCluster": "DeleteClustersRequest"
},
"clusters": {
"ShoppingList": {
"package": "com.google.android.engage.shopping.datamodel.ShoppingList",
"fields": {
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"itemLabels": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addItemLabel(String)",
"getter": "getItemLabels()",
"adderAll": "addItemLabels(List<String>)"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(int)",
"getter": "getNumberOfItems()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"lastUserInteractionTimestampMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastUserInteractionTimestampMillis(long)",
"getter": "getLastUserInteractionTimestampMillis()"
}
}
},
"ShoppingReorderCluster": {
"package": "com.google.android.engage.shopping.datamodel.ShoppingReorderCluster",
"fields": {
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"itemLabels": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addItemLabel(String)",
"getter": "getItemLabels()",
"adderAll": "addItemLabels(List<String>)"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(int)",
"getter": "getNumberOfItems()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"ShoppingCart": {
"package": "com.google.android.engage.shopping.datamodel.ShoppingCart",
"fields": {
"title": {
"type": "String",
"requirement": "Optional",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"actionText": {
"type": "String",
"requirement": "Optional",
"setter": "setActionText(String)",
"getter": "getActionText()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"itemLabels": {
"type": "List<List<String>>",
"requirement": "Optional",
"adder": "addItemLabel(String)",
"getter": "getItemLabels()",
"adderAll": "addItemLabels(List<String>)"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(int)",
"getter": "getNumberOfItems()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"lastUserInteractionTimestampMillis": {
"type": "Long",
"requirement": "Optional",
"setter": "setLastUserInteractionTimestampMillis(long)",
"getter": "getLastUserInteractionTimestampMillis()"
}
}
},
"ShoppingOrderTrackingCluster": {
"package": "com.google.android.engage.shopping.datamodel.ShoppingOrderTrackingCluster",
"fields": {
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Optional",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"status": {
"type": "String",
"requirement": "Required",
"setter": "setStatus(String)",
"getter": "getStatus()"
},
"orderTime": {
"type": "Long",
"requirement": "Required",
"setter": "setOrderTime(long)",
"getter": "getOrderTime()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"orderReadyTimeWindow": {
"type": "OrderReadyTimeWindow",
"requirement": "Optional",
"setter": "setOrderReadyTimeWindow(OrderReadyTimeWindow)",
"getter": "getOrderReadyTimeWindow()"
},
"numberOfItems": {
"type": "Integer",
"requirement": "Optional",
"setter": "setNumberOfItems(Integer)",
"getter": "getNumberOfItems()"
},
"orderDescription": {
"type": "String",
"requirement": "Optional",
"setter": "setOrderDescription(String)",
"getter": "getOrderDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"orderValue": {
"type": "Price",
"requirement": "Optional",
"setter": "setOrderValue(Price)",
"getter": "getOrderValue()"
},
"shoppingOrderType": {
"type": "@ShoppingOrderType int",
"requirement": "Required",
"setter": "setShoppingOrderType(@ShoppingOrderType int)",
"getter": "getShoppingOrderType()"
},
"trackingId": {
"type": "String",
"requirement": "Optional",
"setter": "setTrackingId(String)",
"getter": "getTrackingId()"
}
}
}
},
"intents": {
"ACTION_PUBLISH_SHOPPING_CART": "com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART",
"ACTION_PUBLISH_SHOPPING_LIST": "com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST",
"ACTION_PUBLISH_REORDER_CLUSTER": "com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER",
"ACTION_PUBLISH_ORDER_TRACKING_CLUSTER": "com.google.android.engage.action.shopping.PUBLISH_ORDER_TRACKING_CLUSTER"
}
}

228
.agents/skills/engage-sdk-integration/references/schemas/social.md Normal file
View File

@@ -0,0 +1,228 @@
This file defines the schema for the SOCIAL vertical in the Engage SDK.
{
"client": "com.google.android.engage.social.service.AppEngageSocialClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED"
],
"entities": {
"SocialPostEntity": {
"package": "com.google.android.engage.social.datamodel.SocialPostEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"genericPost": {
"type": "GenericPost",
"requirement": "Required",
"setter": "setGenericPost(GenericPost)",
"getter": "getGenericPost()"
},
"profile": {
"type": "Profile",
"requirement": "Optional",
"setter": "setProfile(Profile)",
"getter": "getProfile()"
},
"interactions": {
"type": "List<Interaction>",
"requirement": "Optional",
"adder": "addInteraction(Interaction)",
"getter": "getInteractions()"
},
"allInteractions": {
"type": "List<List<Interaction>>",
"requirement": "Optional",
"adder": "addAllInteraction(Interaction)",
"adderAll": "addAllInteraction(List<Interaction>)"
}
}
},
"PortraitMediaEntity": {
"package": "com.google.android.engage.social.datamodel.PortraitMediaEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"portraitMediaPost": {
"type": "PortraitMediaPost",
"requirement": "Required",
"setter": "setPortraitMediaPost(PortraitMediaPost)",
"getter": "getPortraitMediaPost()"
},
"profile": {
"type": "Profile",
"requirement": "Optional",
"setter": "setProfile(Profile)",
"getter": "getProfile()"
},
"interactions": {
"type": "List<List<Interaction>>",
"requirement": "Optional",
"adder": "addInteractions(Interaction)",
"getter": "getInteractions()",
"adderAll": "addInteractions(List<Interaction>)"
},
"recommendationReason": {
"type": "@NonNull RecommendationReason",
"requirement": "Optional",
"setter": "setRecommendationReason(@NonNull RecommendationReason)",
"getter": "getRecommendationReason()"
},
"platformSpecificPlaybackUris": {
"type": "List<@NonNull PlatformSpecificUri>",
"requirement": "Optional",
"adder": "addPlatformSpecificPlaybackUri(@NonNull PlatformSpecificUri)",
"getter": "getPlatformSpecificPlaybackUris()",
"adderAll": "addPlatformSpecificPlaybackUris(List<PlatformSpecificUri>)"
},
"commentsSummary": {
"type": "@NonNull String",
"requirement": "Optional",
"setter": "setCommentsSummary(@NonNull String)",
"getter": "getCommentsSummary()"
},
"interaction": {
"requirement": "Optional",
"setter": "setInteraction(Interaction)",
"type": "Interaction",
"getter": "getInteraction()"
}
}
},
"PersonEntity": {
"package": "com.google.android.engage.social.datamodel.PersonEntity",
"fields": {
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"profile": {
"type": "Profile",
"requirement": "Required",
"setter": "setProfile(Profile)",
"getter": "getProfile()"
},
"headerImage": {
"type": "Image",
"requirement": "Optional",
"setter": "setHeaderImage(Image)",
"getter": "getHeaderImage()"
},
"popularity": {
"type": "Popularity",
"requirement": "Optional",
"setter": "setPopularity(Popularity)",
"getter": "getPopularity()"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()"
},
"locations": {
"type": "Address",
"requirement": "Optional"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"contentCategories": {
"type": "List<@EligibleContentCategory int>",
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"adderAll": "addContentCategories(List<Integer>)"
},
"location": {
"requirement": "Optional",
"setter": "setLocation(Address)",
"type": "Address",
"getter": "getLocation()"
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"deleteUserManagementCluster": "DeleteClustersRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest"
},
"intents": {}
}

923
.agents/skills/engage-sdk-integration/references/schemas/travel.md Normal file
View File

@@ -0,0 +1,923 @@
This file defines the schema for the TRAVEL vertical in the Engage SDK.
{
"client": "com.google.android.engage.travel.service.AppEngageTravelClient",
"clusterTypes": [
"TYPE_RECOMMENDATION",
"TYPE_FEATURED",
"TYPE_RESERVATION",
"TYPE_CONTINUE_SEARCH"
],
"entities": {
"EventEntity": {
"package": "com.google.android.engage.travel.datamodel.EventEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"title": {
"type": "@NonNull String",
"requirement": "Required",
"setter": "setTitle(@NonNull String)",
"getter": "getTitle()"
},
"startTime": {
"type": "Long",
"requirement": "Required",
"setter": "setStartTime(Long)",
"getter": "getStartTime()"
},
"localizedStartTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedStartTime(LocalizedTimestamp)",
"getter": "getLocalizedStartTime()"
},
"eventMode": {
"type": "@EventMode int",
"requirement": "Required",
"setter": "setEventMode(@EventMode int)",
"getter": "getEventMode()"
},
"locations": {
"type": "Address",
"requirement": "Required"
},
"endTime": {
"type": "Long",
"requirement": "Optional",
"setter": "setEndTime(Long)",
"getter": "getEndTime()"
},
"localizedEndTime": {
"type": "LocalizedTimestamp",
"requirement": "Optional",
"setter": "setLocalizedEndTime(LocalizedTimestamp)",
"getter": "getLocalizedEndTime()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"contentCategories": {
"type": "List<@EligibleContentCategory int>",
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"adderAll": "addContentCategories(List<Integer>)"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"location": {
"requirement": "Required",
"setter": "setLocation(Address)",
"type": "Address",
"getter": "getLocation()",
"requiredFor": [
"Required if strikethrough price is provided"
]
}
}
},
"LodgingEntity": {
"package": "com.google.android.engage.travel.datamodel.LodgingEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"locations": {
"type": "Address",
"requirement": "Required"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"availabilityTimeWindow": {
"type": "AvailabilityTimeWindow",
"requirement": "Optional",
"setter": "setAvailabilityTimeWindow(AvailabilityTimeWindow)",
"getter": "getAvailabilityTimeWindow()"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"location": {
"requirement": "Required",
"setter": "setLocation(Address)",
"type": "Address",
"getter": "getLocation()",
"requiredFor": [
"Required if strikethrough price is provided"
]
}
}
},
"PointOfInterestEntity": {
"package": "com.google.android.engage.travel.datamodel.PointOfInterestEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionLinkUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionLinkUri(Uri)",
"getter": "getActionLinkUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"locations": {
"type": "Address",
"requirement": "Required"
},
"availabilityTimeWindow": {
"type": "AvailabilityTimeWindow",
"requirement": "Optional",
"setter": "setAvailabilityTimeWindow(AvailabilityTimeWindow)",
"getter": "getAvailabilityTimeWindow()"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"contentCategories": {
"type": "List<@EligibleContentCategory int>",
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"adderAll": "addContentCategories(List<Integer>)"
},
"lastEngagementTime": {
"type": "Instant",
"requirement": "Optional",
"setter": "setLastEngagementTime(Instant)",
"getter": "getLastEngagementTime()",
"requiredFor": [
"ContinueSearchCluster"
]
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
},
"location": {
"requirement": "Required",
"setter": "setLocation(Address)",
"type": "Address",
"getter": "getLocation()",
"requiredFor": [
"RecommendationCluster"
]
}
}
},
"LodgingReservationEntity": {
"package": "com.google.android.engage.travel.datamodel.LodgingReservationEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"address": {
"type": "Address",
"requirement": "Required",
"setter": "setAddress(Address)",
"getter": "getAddress()"
},
"checkInTime": {
"type": "Long",
"requirement": "Required",
"setter": "setCheckInTime(long)",
"getter": "getCheckInTime()"
},
"localizedCheckInTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedCheckInTime(LocalizedTimestamp)",
"getter": "getLocalizedCheckInTime()"
},
"checkOutTime": {
"type": "Long",
"requirement": "Required",
"setter": "setCheckOutTime(long)",
"getter": "getCheckOutTime()"
},
"localizedCheckOutTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedCheckOutTime(LocalizedTimestamp)",
"getter": "getLocalizedCheckOutTime()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()",
"requiredFor": [
"Required if strikethrough price is provided",
"Mutually required with other rating fields"
]
},
"reservationId": {
"type": "String",
"requirement": "Optional",
"setter": "setReservationId(String)",
"getter": "getReservationId()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"EventReservationEntity": {
"package": "com.google.android.engage.travel.datamodel.EventReservationEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"startTime": {
"type": "Long",
"requirement": "Required",
"setter": "setStartTime(Long)",
"getter": "getStartTime()"
},
"localizedStartTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedStartTime(LocalizedTimestamp)",
"getter": "getLocalizedStartTime()"
},
"eventMode": {
"type": "@EventMode int",
"requirement": "Required",
"setter": "setEventMode(@EventMode int)",
"getter": "getEventMode()"
},
"location": {
"type": "Address",
"requirement": "Required",
"setter": "setLocation(Address)",
"getter": "getLocation()"
},
"endTime": {
"type": "Long",
"requirement": "Optional",
"setter": "setEndTime(Long)",
"getter": "getEndTime()"
},
"localizedEndTime": {
"type": "LocalizedTimestamp",
"requirement": "Optional",
"setter": "setLocalizedEndTime(LocalizedTimestamp)",
"getter": "getLocalizedEndTime()"
},
"serviceProvider": {
"type": "ServiceProvider",
"requirement": "Optional",
"setter": "setServiceProvider(ServiceProvider)",
"getter": "getServiceProvider()"
},
"badges": {
"type": "List<Badge>",
"requirement": "Optional",
"adder": "addBadge(Badge)",
"adderAll": "addBadges(List<Badge>)"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"rating": {
"type": "Rating",
"requirement": "Optional",
"setter": "setRating(Rating)",
"getter": "getRating()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"contentCategories": {
"type": "List<@EligibleContentCategory int>",
"requirement": "Optional",
"adder": "addContentCategory(@EligibleContentCategory int)",
"adderAll": "addContentCategories(List<Integer>)"
},
"reservationId": {
"type": "String",
"requirement": "Optional",
"setter": "setReservationId(String)",
"getter": "getReservationId()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"TransportationReservationEntity": {
"package": "com.google.android.engage.travel.datamodel.TransportationReservationEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"departureTime": {
"type": "Long",
"requirement": "Required",
"setter": "setDepartureTime(Long)",
"getter": "getDepartureTime()"
},
"localizedDepartureTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedDepartureTime(LocalizedTimestamp)",
"getter": "getLocalizedDepartureTime()"
},
"arrivalTime": {
"type": "Long",
"requirement": "Required",
"setter": "setArrivalTime(Long)",
"getter": "getArrivalTime()"
},
"localizedArrivalTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedArrivalTime(LocalizedTimestamp)",
"getter": "getLocalizedArrivalTime()"
},
"transportationType": {
"type": "@TransportationType int",
"requirement": "Required",
"setter": "setTransportationType(@TransportationType int)",
"getter": "getTransportationType()"
},
"departureLocation": {
"type": "Address",
"requirement": "Optional",
"setter": "setDepartureLocation(Address)",
"getter": "getDepartureLocation()"
},
"arrivalLocation": {
"type": "Address",
"requirement": "Optional",
"setter": "setArrivalLocation(Address)",
"getter": "getArrivalLocation()"
},
"serviceProvider": {
"type": "ServiceProvider",
"requirement": "Optional",
"setter": "setServiceProvider(ServiceProvider)",
"getter": "getServiceProvider()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"transportationNumber": {
"type": "String",
"requirement": "Optional",
"setter": "setTransportationNumber(String)",
"getter": "getTransportationNumber()"
},
"boardingTime": {
"type": "Long",
"requirement": "Optional",
"setter": "setBoardingTime(Long)",
"getter": "getBoardingTime()"
},
"localizedBoardingTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedBoardingTime(LocalizedTimestamp)",
"getter": "getLocalizedBoardingTime()"
},
"reservationId": {
"type": "String",
"requirement": "Optional",
"setter": "setReservationId(String)",
"getter": "getReservationId()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
},
"VehicleRentalReservationEntity": {
"package": "com.google.android.engage.travel.datamodel.VehicleRentalReservationEntity",
"fields": {
"entityId": {
"type": "String",
"requirement": "Optional",
"setter": "setEntityId(String)",
"getter": "getEntityId()"
},
"posterImages": {
"type": "List<Image>",
"requirement": "Required",
"adder": "addPosterImage(Image)",
"getter": "getPosterImages()",
"adderAll": "addPosterImages(List<Image>)"
},
"actionUri": {
"type": "Uri",
"requirement": "Required",
"setter": "setActionUri(Uri)",
"getter": "getActionUri()"
},
"title": {
"type": "String",
"requirement": "Required",
"setter": "setTitle(String)",
"getter": "getTitle()"
},
"description": {
"type": "String",
"requirement": "Optional",
"setter": "setDescription(String)",
"getter": "getDescription()"
},
"subtitles": {
"type": "List<String>",
"requirement": "Optional",
"adder": "addSubtitle(String)",
"adderAll": "addSubtitles(List<String>)"
},
"pickupTime": {
"type": "Long",
"requirement": "Required",
"setter": "setPickupTime(Long)",
"getter": "getPickupTime()"
},
"localizedPickupTime": {
"type": "LocalizedTimestamp",
"requirement": "Required",
"setter": "setLocalizedPickupTime(LocalizedTimestamp)",
"getter": "getLocalizedPickupTime()"
},
"returnTime": {
"type": "Long",
"requirement": "Optional",
"setter": "setReturnTime(Long)",
"getter": "getReturnTime()"
},
"localizedReturnTime": {
"type": "LocalizedTimestamp",
"requirement": "Optional",
"setter": "setLocalizedReturnTime(LocalizedTimestamp)",
"getter": "getLocalizedReturnTime()"
},
"pickupAddress": {
"type": "Address",
"requirement": "Optional",
"setter": "setPickupAddress(Address)",
"getter": "getPickupAddress()"
},
"returnAddress": {
"type": "Address",
"requirement": "Optional",
"setter": "setReturnAddress(Address)",
"getter": "getReturnAddress()"
},
"serviceProvider": {
"type": "ServiceProvider",
"requirement": "Optional",
"setter": "setServiceProvider(ServiceProvider)",
"getter": "getServiceProvider()"
},
"price": {
"type": "Price",
"requirement": "Optional",
"setter": "setPrice(Price)",
"getter": "getPrice()",
"requiredFor": [
"Required if strikethrough price is provided"
]
},
"priceCallout": {
"type": "String",
"requirement": "Optional",
"setter": "setPriceCallout(String)",
"getter": "getPriceCallout()"
},
"confirmationId": {
"type": "String",
"requirement": "Optional",
"setter": "setConfirmationId(String)",
"getter": "getConfirmationId()"
},
"displayTimeWindows": {
"type": "List<DisplayTimeWindow>",
"requirement": "Optional",
"adder": "addDisplayTimeWindow(DisplayTimeWindow)",
"getter": "getDisplayTimeWindows()"
},
"allDisplayTimeWindows": {
"type": "List<List<DisplayTimeWindow>>",
"requirement": "Optional",
"adder": "addAllDisplayTimeWindow(DisplayTimeWindow)",
"adderAll": "addAllDisplayTimeWindow(List<DisplayTimeWindow>)"
}
}
}
},
"methods": {
"isServiceAvailable": null,
"publishRecommendationClusters": "PublishRecommendationClustersRequest",
"publishFeaturedCluster": "PublishFeaturedClusterRequest",
"publishUserAccountManagementRequest": "PublishUserAccountManagementRequest",
"updatePublishStatus": "PublishStatusRequest",
"publishContinueSearchCluster": "PublishContinueSearchClusterRequest",
"publishReservationCluster": "PublishReservationClusterRequest",
"deleteRecommendationsClusters": "DeleteClustersRequest",
"deleteFeaturedCluster": "DeleteClustersRequest",
"deleteUserManagementCluster": "DeleteClustersRequest",
"deleteContinueSearchCluster": "DeleteClustersRequest",
"deleteReservationCluster": "DeleteClustersRequest"
},
"clusters": {
"ContinueSearchCluster": {
"package": "com.google.android.engage.travel.datamodel.ContinueSearchCluster",
"fields": {
"pointOfInterestEntities": {
"type": "List<PointOfInterestEntity>",
"requirement": "Required",
"adder": "addPointOfInterestEntity(PointOfInterestEntity)"
}
}
},
"ReservationCluster": {
"package": "com.google.android.engage.travel.datamodel.ReservationCluster",
"fields": {
"lodgingReservationEntities": {
"type": "List<LodgingReservationEntity>",
"requirement": "Optional",
"adder": "addLodgingReservationEntity(LodgingReservationEntity)"
},
"vehicleRentalReservationEntities": {
"type": "List<VehicleRentalReservationEntity>",
"requirement": "Optional",
"adder": "addVehicleRentalReservationEntity(VehicleRentalReservationEntity)"
},
"transportationReservationEntities": {
"type": "List<TransportationReservationEntity>",
"requirement": "Optional",
"adder": "addTransportationReservationEntity(TransportationReservationEntity)"
},
"eventReservationEntities": {
"type": "List<EventReservationEntity>",
"requirement": "Optional",
"adder": "addEventReservationEntity(EventReservationEntity)"
},
"restaurantReservationEntities": {
"type": "List<RestaurantReservationEntity>",
"requirement": "Optional",
"adder": "addRestaurantReservationEntity(RestaurantReservationEntity)"
}
}
}
},
"intents": {
"ACTION_PUBLISH_CONTINUE_SEARCH_CLUSTER": "com.google.android.engage.action.travel.PUBLISH_CONTINUE_SEARCH",
"ACTION_PUBLISH_RESERVATION_CLUSTER": "com.google.android.engage.action.travel.PUBLISH_RESERVATION"
}
}

1226
.agents/skills/engage-sdk-integration/references/schemas/tv.md Normal file
View File

File diff suppressed because it is too large Load Diff

1137
.agents/skills/engage-sdk-integration/references/schemas/watch.md Normal file
View File

File diff suppressed because it is too large Load Diff