# TOP 0.9.x to 1.0.0 Migration Guide

This guide covers significant changes made for the `TOP` in the `1.0` release:

- Breaking Changes - Existing code using versions of `TOP` before `1.0.0-alpha.1` must update items specified here
- Suggested Changes - Existing code does not need to change, but the changes make for easier implementation and better code readability

## Breaking Changes

Some breaking changes were made for version `1.0.0` to simplify integration. Anyone using version `1.0.0-alpha.1` and lower will need to make minor updates. The breaking changes are the following:

- Build: Artifact changes
- Auth: Allow string values for token service keys
- Config: Plugin structure
- Cues: Simplified structure

### Build: Artifact changes

Prior to `1.0.0-rc.1`, there were multiple artifacts produced for each version (`1`, `1b`, `2`, `2b`). Each artifact represented different dependency sets.

In `1.0.0-rc.1`, that has been consolidated into one artifact, `top.sdk.min.js`. Example of a script include using the new artifact:

    <script src="//turnip.cdn.turner.com/top/core/1.0.0-rc.1/default/top.sdk.min.js"></script>

### Auth: Allow string values for token service keys

Prior to `1.0.0-alpha.1` available auth token keys were restricted to what was defined on the AuthTokenType enum (see example):

    var AuthTokenType = com.turner.top.sdk.common.auth.AuthTokenType;
    var entry = ContentEntryBuilder.create()
                    .addFile({ url: "//turnerlive.akamaized.net/hls/live/572096/tbse/noslate/tv/master.m3u8" })
                    .requireAuth(AuthTokenType.Token_Spe)
                    .build();

    player.play(entry);

In `1.0.0-alpha.1` the AuthTokenType.Token_Spe enum changed to AuthTokenType.Spe which is now a string. `AuthTokenType.Spe` should be used when referring to the default token service (see example):

    player.play({
        url: "//turnerlive.akamaized.net/hls/live/572096/tbse/noslate/tv/master.m3u8",
        auth: {
            type: TOP.auth.AuthTokenType.Spe
        }
    },
    options);

A custom string can also be used for scenarios where a custom auth service is used, e.g. free preview (see example):

    var player = TOP.createAndInitPlayer({
        config: {
            auth: [
                {
                    type       : "testService",
                    serviceUrl : "//token.vgtf.net/token/token_spe"
                }
            ]
        }
    });
    player.play({
        url: "//turnerlive.akamaized.net/hls/live/572096/tbse/noslate/tv/master.m3u8",
        auth: {
            type: "testService"
        }
    });

### Config: Plugin Structure

Prior to `1.0.0-alpha.1` the `plugins` config resided in the `sdk` config (see example):

    var playerConfig = {
        config : {
            sdk : {
                plugins : []
            }
        }
    };

In `1.0.0-alpha.1` the `plugins` config has been lifted up so it's on the same level as `sdk` (see example):

    var playerConfig = {
        config : {
            plugins : []
        }
    };

### Cues: Simplified structure

Prior to `1.0.0-rc.1`, for the cue events kicked out through the API (`cueProcessed`, `cueActivated`), the structure of the result object was nested several levels:

    player.events().cueActivated.listen(result => {
        // cue represents the metdata payload
        const cue = result.cue;

        console.log(cue.data.time);     // The trigger time for this cue
        console.log(cue.data.result);   // The parsed payload for this cue
    });

In `1.0.0-rc.1`, the cue result has been simplified:

    player.events().cueActivated.listen(result => {
        // cue represents the metdata payload
        const cue = result.cue;

        console.log(cue.time);     // The trigger time for this cue
        console.log(cue.data);   // The parsed payload for this cue
    });

## Suggested Changes

There are also changes meant to make using `TOP` easier. These changes are not required and the previous implementations still work. Those items are the following:

- API: Type Aliases
- API: Create and Init Player

### API: Type Aliases

Prior to `0.9.5` full classpaths had to be referenced to use specific `TOP` classes/types (see example):

    var AuthTokenType = com.turner.top.sdk.common.auth.AuthTokenType;

In `0.9.5` type aliases were implemented to act as shortcuts that point to the same classes needed to use `TOP`. They can be statically referenced from the `TOP` class (see example)

    var AuthTokenType = TOP.auth.AuthTokenType;

### API: Create and Init Player

Prior to `0.9.5` instantiating `TOP` player required a few method calls to create the player, set up listeners, and initialize the player (see example):

    // Create the player
    var player = TOP.createPlayer();

    // Setup player listeners
    player.events().listenFor({
        playerReady : function(result) {

        }
    });

    // Sample config
    var playerConfig = {
        element: document.getElementById("myVideoContainer"),
        config : {

        }
    };

    // Initialize the player, optionally passing in a config
    player.init(playerConfig);

In `0.9.5` the above can be consolidated into `TOP.createAndInitPlayer` (see player creation and example):

    var player = TOP.createAndInitPlayer({
        element: document.getElementById("myVideoContainer"),
        config : {

        },
        events: {
            playerReady : function(result) {

            }
        }
    });