Skip to end of metadata
Go to start of metadata

Guided Setup

Guided Setup is done only during the initial setup process or when the device has been reset to factory defaults. This process is designed to be developer independent and is performed one time. If reconfiguration of these attributes is needed, it can be done through the Settings option on the main menu. Guided Setup configures basic network services (wired or wireless) and performs a series of tests to ensure the device can communicate properly.

Guided Setup then takes the user through a rendezvous style registration process to link the Roku device to an account on An account defines a unique channel line-up for a user based on the channels they have selected. All devices linked to a specific account will receive the same channel line-up.


Developer applications may also wish to present a customized view to their individual users. The standard way to support this on the Roku Streaming Player is to provide a registration process that associates the device with a user-specific account on the developer's site. Each developer needing account registration will be required to implement a registration UI as part of their application. This UI may be called in one of two ways:

  • On first use of any service, the system may detect that a service has not yet been configured and guide the user through the registration process for that developer. This method makes it easy for new services to be added to the device over time and presents a one-time configuration step on first use. The Netflix channel is a good example of this type of registration.
  • On first use of an account specific feature, the user may be prompted to register their device and obtain access to these enhanced feature(s). An example of this approach would be a service that may be used without an account to provide a base level of functionality, but that requires account linking for advanced features such as personalization, favorites or other similar features. The Amazon channel is a good example of this type of registration. You can see it when entering "Your Video Library". Flickr also uses this approach and that source is available in the SDK examples.

The process of registration involves linking a device (identified by a unique electronic serial number) with an account on a specific service. Account registration and device linking can be accomplished in two ways. The preferred method is through the implementation of a code-based "rendezvous" style registration system. An alternative username/password style of registration may also be used. 

A rendezvous registration system presents the user with a simple on-screen code on the device during registration. The user enters this code on the developer's website to establish a link between the device and the users account. This type of registration requires the third-party developer to implement the following features:

    • A web services API for obtaining a registration code and specifying retry parameters
    • A web services API for obtaining the registration result and associated user token
    • Web pages to register/un-register a device on the developer's site

A username/password registration scheme may be desirable for some services. In these cases, the user will enter the username and password for their account during setup. This info will be used in subsequent calls to the third-party service to obtain the necessary credentials to make web services requests. This method is provided solely for compatibility with a variety of services. The rendezvous style registration is preferred both for its usability as well as the security benefits. 

Any user account information or tokens exchanged during the registration process may be stored in the application specific portion of the registry as persistent data. This data may be accessed again at any time by the application when making web services calls to the developer's back-end service.

It is important not to keep any permanent device association stored on your server. Roku wants to give users the ability to do a "Factory Reset" and have any personally identifiable information wiped from the device. This includes removing any association with server side accounts. Account tokens stored in the device registry meet this requirement nicely as the device registry is removed with a "Factory Reset".

Details and a walkthrough of implementing device/account linking and registration can be found in the Device Linking and Registration Guide.


  • No labels