X1 Apps can utilize cookies the same way they would in any browser. You use the normal access point (document.cookie) and parse as you would in any other web application. There are no special methods for reading or writing cookies. At the code level you operate as you would in any browser. Note, however, that to remain compliant with the Program and Distribution Agreements, X1 Apps may not implement any functionality that sets third-party cookies without a customized agreement.

Cloud Cookies on the X1 Platform

The X1 Platform uses Cloud Cookies to allow X1 Apps to have access to a persistent cookie functionality by utilizing the cloud. As you create or update cookies in the browser, the X1 Platform will write these session cookies to the X1 Platform cloud during the X1 App session and when the user exits your X1 App.

A cloud cookie is stored in the cloud, as compared to cookies stored in the browser, which remain on the device between sessions.

Cloud Cookie Flow

Before your X1 App is launched by the browser, our system checks to see if there are any cookies for your X1 App associated with the X1 Device or account that initiated the launch. If there are cookies that need to be pulled down from the cloud, those cookies will be made available in the browser before your X1 App is launched. This means your cookies will be there, ready, when your X1 App launches.

Testing Cloud Cookies in Development

Because it takes time to read and write from the cloud, there is a short delay from when a user exits your X1 App to when the cookies are completely written and available for the next launch. This delay is variable, and most commonly presents itself when a user relaunches the X1 App immediately after exiting from it. During development and testing, you may observe this issue by seeing older cookies during a relaunch of the X1 App. The fix is to simply pause between launches. Most end users are not impacted by this delay, as they do not generally relaunch an app immediately upon exit.

Cookies are tied, in part, to the X1 App name. If you are using our test tools to launch your X1 App via URL, you must use the same name between launches if you want to have your cookies available on subsequent launches. This is not an issue if you are launching from a tile; the X1 App name in that case is fixed as part of the configuration. If you need to erase (or rename) cloud cookies associated with an X1 App tile for a given X1 Device you need to contact your partner manager. You can clear all cookies by simply launching the X1 App with a different name, which will bring the X1 App back to the "first launch" state, as far as cookies are concerned. Keep in mind that if you later reuse an old X1 App name, the cookies last associated with that X1 App name for a given X1 Device will be served.

Types of Cloud Cookies

There are two types of cloud cookies on the X1 Platform and they have slightly different applications. There are device cookies and account cookies. We advise that your X1 App only use one type of cloud cookies. We will store your cloud cookie preference as part of the configuration of the X1 App tile. If you use our test tools, you can select your preference for either device or account level cloud cookies when launching your X1 App from a URL.

Device Cookies

Device Cookies are exactly what their name implies. These are cookies tied to your X1 App on a specific X1 Device. If there are multiple X1 Devices in the same household, each one would have its own set of cookies. If a user were to use the X1 App on one X1 Device and the X1 App was using cookies to store, for example, high scores, that information would not be available to that user on another X1 Device.

Account Cookies

Account Cookies are tied to a customer account. Effectively this is a household.

If the household has multiple X1 Devices (ex: Living Room, Bedroom, and Den), when Account Cookies are used the Account Cookie is available on any X1 Device on the account.

For example, a user could launch your X1 App on their Living Room X1 Device, exit, and launch it later on their Den X1 Device. The Den X1 Device would access cookies from the earlier session.

Note
Account cookies are not designed for simultaneous use. If two people are running your X1 App on two X1 Devices under the same account, the last written cookies are the ones that will persist. Account cookies are designed to let a person move between the X1 Devices associated with the account and have a seamless experience.

For purposes of development and testing, using account cookies, we advise that you minimize overlap when running/testing your X1 App on X1 Devices under the same Account. With multiple team members working at the same time you will be overwriting each other's cookies and will have an inconsistent experience with cookies in general.

If the Account Cookie model is the best choice for your X1 App from the perspective of your end user, you should use Account Cookies. However, it may be best to start development under with Device Cookies so that the team does not run into the issues above. When your X1 App moves to a more structured test stage, switch to Account Cookies.

X1 Platform Cookie Restrictions & Disclosures

Third-Party Cookies

X1 Apps may not implement any functionality that sets third-party cookies without a customized agreement.

Clear Cookies and Local Storage Data

The X1 Platform provides functionality for users to clear all cookies and local storage on their X1 Devices, including Device and Account Cloud Cookies.