The contents of the section are for informative purposes only and are intended to provide guidance to developers and to assist in their use and understanding of the normative material.

Guidance for Framework Developers

Functional Decomposition

This API decomposes the functionality into four groups: Package Management, Content Access, Account Access, and Player Interaction. Framework implementers are responsible for providing all four. There is, however, neither requirement nor assumption as to how many software components are used to implement the functionality. Framework developers may choose to provide a single construct (e.g., a JavaScript file) or split the functionality across multiple constructs for purposes of modularity, performance, or flexibility.

Package Management

The Framework has ultimate responsibility for ensuring that the software providing the Interactive Experience is stable and well-behaved. At the same time, Framework developers have no guarantee that a deployed Package is entirely bug free or can properly respond to all external events. The Framework should, therefore, take care to ensure that, as the “last resort” in case of a fatal error, any allocated resources are released and a final garbage collection and clean-up is performed.
Framework developers may also API to monitor the state-behavior of a Package and insure that it is still alive and function. This may be done via the Package Management API group’s getState() method (see Section 4.3.7)

Guidance for Package Developers

Mobile Users

Any viewing environment based on a mobile platform has several characteristics that must be allowed for. First and foremost is that any application running in a mobile OS must be able to cleanly handle suspension and resumption caused by preemption due to an incoming call. Second is the need to deal with the variable and intermittent nature of mobile networks. Third is the need to handle events not encountered when operating in a desktop environment such as a change in screen layout due to reorientation of the device or warnings of low battery power.
Assignment of responsibilities for the correct handling of these situations is outside the scope of this API. Package developers should, therefore, not assume that the Framework will insure correct behavior. The roles and responsibilities of each component in this regard should be identified as part of the integration process. Access to these events is outside the scope of this API and the mechanism for accessing may depend on the viewing environment (e.g., iOS vs. Android), the implementation language (e.g., Java vs. JavaScript) or both. See Section 9.2: “Mobile Environments” for additional discussion of these issues.

Single User with Multiple Devices

The use of multiple devices by a single individual is an increasing trend. A user may begin watching a movie on a tablet device while coming home from work on the train, then finish watching after dinner on a desktop PC. The ability to pause an activity on one device and seamlessly resume on another is referred to global session persistence. This has become a characteristic that consumers expect to find supported.
The back-end services and infrastructure that are used to provide this type of capability, while not difficult to provide, are well outside the scope of this API. Each content provider will be free to decide if, and how, a Package implementation will support this type of functionality.
In the event a Retailer maintains Account-specific usage history information the Cross-Platform Extras API defines methods to allow a package, when paused during a session, to communicate to the framework those aspects of the session state it wishes to persist and that when started it may obtain from the framework the data necessary to (a) determine that a previous session state exists and (b) retrieve and restore the paused session. Whether or not it may do so on a global or local basis will be determined by the capabilities the retailer chooses to offer via their framework implementation. Whether or not a Package uses this in lieu of, or in combination with, its own persistence mechanisms is outside the scope of this API.