@amazon-devices/kepler-media-account-login

The Vega Media Account Login API provides a way for apps to report their authentication status to the system.

Remarks

Apps need to refresh the user’s login status upon each launch, which is done by the Account Login API. There are two account login states: signed in, and signed out. By keeping the login status up-to-date, apps make sure that users have access to appropriate content and features. The interface allows apps to communicate a boolean value indicating whether a user is logged in, both at launch and whenever the login state changes. The system can also query this status as needed, enabling a personalized user experience. Products can leverage this information to feature or filter content from services where the user is already authenticated, allowing for instant access to content. The Account Login functionality offers two key components for managing authentication status: the updateStatus method, and the handleReadStatus callback function. The updateStatus method reports an app’s current login status for real-time updates when the authentication state changes. The handleReadStatus callback function can respond to system queries about the app’s current login status. Both methods use the StatusType for account status, with two possible values: SIGNED_IN and SIGNED_OUT.

Get started

Setup

Add the following library dependency to the dependencies section of your package.json file.

    "@amazon-devices/kepler-media-account-login": "~1.1.24",
    "@amazon-devices/headless-task-manager": "~1.2.4"

In your manifest.toml, add the following privileges required to access. Note: When modifying the manifest entries, replace com.amazondeveloper.media.sample with your app’s package ID, as seen in the following example.

schema-version = 1

[package]
title = "<Your app title>"
id = "com.amazondeveloper.media.sample"

[components]

[[components.interactive]]
id = "com.amazondeveloper.media.sample.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
# The category "com.amazon.category.kepler.media" is only necessary for the primary component, which is identified in the [[extras]]
# section of the manifest using the "component-id" value.
categories = ["com.amazon.category.main", "com.amazon.category.kepler.media"]

[[components.service]]
id = "com.amazondeveloper.media.sample.interface.provider"
runtime-module = "/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"

[processes]

[[processes.group]]
component-ids = ["com.amazondeveloper.media.sample.main"]

[[processes.group]]
component-ids = ["com.amazondeveloper.media.sample.interface.provider"]

[offers]

[[offers.interaction]]
id = "com.amazondeveloper.media.sample.main"

[[offers.service]]
id = "com.amazondeveloper.media.sample.interface.provider"
required-privileges = ["com.amazon.multimedia.privilege.session.manage"]

[[message]]
uri = "pkg://com.amazondeveloper.media.sample.main"
# Match the privileges used in [[offers.interaction]]. If privileges are not added, then use "*".
sender-privileges = ["*"]
receiver-privileges = ["self"]

[[offers.module]]
id = "/com.amazondeveloper.media.sample.module@ISomeUri1"
includes-messages = ["pkg://com.amazondeveloper.media.sample.main"]

[[extras]]
key = "interface.provider"
component-id = "com.amazondeveloper.media.sample.main"

[extras.value.application]
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentLauncherServer"
attribute_options = ["partner-id"]
static-values = { "partner-id" = "<Your partner id>" }

[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IAccountLoginServer"
attribute_options = ["Status"]
# In this manifest example, we have both Content Launcher and Account Login interfaces defined.
# Since the Account Login cluster should be handled by a service component instead of an
# interactive one for responsiveness, we use "override_attribute_component" to redirect
# calls for the "Status" attribute to the service component.
override_attribute_component = { Status = "com.amazondeveloper.media.sample.interface.provider" }

[needs]

[[needs.module]]
# The dot (.) after "media" is intentional in this format. This notation will be changed in a 
# future release.
id = "/com.amazon.kepler.media.@IAccountLogin1"

[[needs.module]]
id = "/com.amazon.kepler.media@IContentLauncher1"

Media apps often require integration with three key APIs:

Content Launcher Cluster API for finding and launching content
Vega Media Controls API for controlling launched media
Account Login API for communicating Account Login status to the system

The Content Launcher and Vega Media Control APIs are most often implemented as an interactive component, which handles Vega media queries. This component is specified in the app manifest’s extras section using the interface.provider key, as shown in the following TOML snippet and in the previous example.

[[extras]]
key = "interface.provider"
component-id = "<primary interactive component-id>"

The Account Login API is implemented as a service app, allowing the system to query Account Login status without waking up the entire app. The Account Login API uses a single “Status” attribute, which is handled by the service component. To ensure proper routing of login status attribute interactions, the app manifest must specify the service component using the override_attribute_component setting, as demonstrated in this TOML example and in the previous example:

override_attribute_component = { Status = "<service component-id implementing Account Login api>" }

Use this approach to optimize system performance and provide a clear separation between media control and account management functionalities. Account Login Integration Guide

API Reference

Classes

AccountLoginServerComponent — Provides factory methods for creating IAccountLoginServerAsync instance.
InternalError — Error class for internal errors, such as setup failures.
InvalidArgumentError — Error class for invalid argument exception.

Interfaces

IAccountLoginHandlerAsync — Interface for handling AccountLogin callbacks asynchronously.
IAccountLoginServerAsync — Interface for the asynchronous AccountLoginServer.
IStatus — Interface representing the login status.
IStatusBuilder — Interface for building Status objects.
KeplerScriptAccountLogin — Facilitates updating an application’s login status.

Enumerations

StatusType — Enumeration representing possible login status types.

​Remarks

​Get started

​Setup

​Related topics

​API Reference

​Classes

​Interfaces

​Enumerations