Lambda Customization (VSK Echo Show)

This guide focuses on tasks that help you identify and update the most important customizable parts of the Lambda.

Use your Catalog Name
- Before Creating the Video Skill
- After Creating the Video Skill
Use your Catalog Content
Use your Database Implementation
Add New Displayable Metadata in Search Results
- Example
The Handler class
Customize the Number of Categories in Landing Page
Next Steps

Use your Catalog Name

Updating the catalog's name can happen either before creating the skill, or after the initial deployment.

Important: Reach out to your Amazon Business contact, if you don't know your catalog name.

Before Creating the Video Skill

Use your own catalog instead of ontv by following these steps:

Change the CATALOG_NAME to your own catalog name in ./lambda/src/utils/constants.js. For example:

export const Constants = {
  ...
  // Replace this with your own Catalog name to use your own Catalog.
  CATALOG_NAME: 'mycatalog',
  ...
}

Change the catalog name in the skill's manifest by editing the ./infrastructure/video-skill/skill.json file. Specifically, update the sourceId value. For example:

    "catalogInformation": [
      {
        "type": "INGESTED_CONTENT_IDENTIFIER",
        "sourceId": "mycatalog"
      }
    ]

Continue with the deployment process from Install, Build, and Deploy the Reference Video Skill: Step 3 onward.

After Creating the Video Skill

If your skill already exists, you must do the following:

Open the Alexa developer console (use this specific link to view your existing skills).
Click Edit on your skill.
Update the Country Specific Configuration with your catalog name
Click Save.
Run the --update --lambda CLI command on your computer.

Use your Catalog Content

Replace the videoDatabase in ./lambda/src/database/database.js with your own video database.

Important: It is highly recommended to keep the same structure in order to ensure consistency across the entire project, and just add new metadata properties in the database.

The Lambda stores an in memory database in ./lambda/src/database/database.js. Its purpose is to maintain and push all your video titles and the S3 video paths. Initially, every video path leads to the sample "Big Buck Bunny" video, with the exception of "Iron Man 2" which maps to a video called "Elephants Dream".

Here is how a typical video object looks like:

{
  id: 'MV009844570000',
  name: 'The Commuter',
  contentType: 'ON_DEMAND',
  videoUrl: 'big-buck-bunny/Bug.Buck.Bunny.mp4',
  actors: ['Liam Neeson', 'Vera Farmiga', 'Patrick Wilson'],
  genre: ['Action', 'Highly Rated', 'Recommended Movies'],
  thumbnailImageDescription: 'The Commuter',
  thumbnailImageSources: [
    {
      url: 'big-buck-bunny/Big.Buck.Bunny.thumbnail.png',
      size: 'SMALL',
      widthPixels: 720,
      heightPixels: 480
    }
  ],
  contentDescription: 'movie',
  parentalControl: 'NOT_REQUIRED',
  absoluteViewingPositionMilliseconds: '0',
  itemType: 'VIDEO',
  releaseYear: '2018',
  selectionAction: 'PLAY',
  runTimeInMilliseconds: 635000,
  runTimeDisplayString: '9m',
  closedCaptionStatus: 'AVAILABLE',
  closedCaptionDisplayString: 'CC',
  viewingDisplayString: 'Play Now',
  reviewsTotalReviewCount: '84823',
  reviewsType: 'FIVE_STAR',
  reviewsRatingDisplayString: '6.3',
  ratingCategory: 'G',
  webPlayerContentType: 'VIDEO'
}

Note: The videoUrl and url values are relevant to the structure of your S3 bucket's content folder, the way it was generated by the CLI tool.

This database structure follows Alexa standards (for example, runTimeInMilliseconds is the video duration as defined in ASK). Update your own video content metadata as defined in this structure.

Note: Remember to run --update --lambda in the CLI tool when you finish updating your database.

Use your Database Implementation

Replace the methods in ./lambda/src/access/in-memory-db-access.js with your own implementation to access your own database and enable searching. In order to properly include your own implementation, update all the .filter methods, such as:

.filter(item => {
  return this._commonIdentifierMatch(item.name, videoName)
})

Tip: Retain the method names and return types, just change the implementation of the methods to point to your own database.

Add New Displayable Metadata in Search Results

If you want to add new metadata in the results of search utterances, here is the process you must follow:

Add the new metadata into your database.js file. (You are strongly advised not to change the existing ones.)
Add the new metadata into the constructor of the VideoData class (located in ./lambda/src/models/database-models/video-metadata.js).
Within the Lambda, reference the search results to your own implementation of the additional metadata.

Note that you must also ensure that the web player gets access to the newly created metadata through a special token, namely the playbackContextToken. Your Lambda passes this token back to Alexa. The playbackContextToken contains a value to describe the media and is passed to your web player through handlers. See the following guides for more details:

Example

Assume that you want to add the production companies of every video in your metadata, as an array of strings. Get started by following this process:

Open your ./lambda/src/database/database.js file.

Add the new production property to your objects, like this:

{
  id: 'MV009844570000',
  name: 'The Commuter',
  production: ['StudioCanal', 'TF1 Films Production', 'The Picture Company', 'Obra Films', 'Canal+', 'Cine +', 'TF1', 'Amazon Prime Video'],
  ...
}

Open the VideoData class in the ./lambda/src/models/database-models/video-metadata.js file.
Add this line to the constructor of the class:
```
this.production = options.production
```

The `Handler` class

This section outlines this class to help you understand the interaction between the Lambda and the web player. At this point there is no need to customize it.

Handler is the main class that receives the request directives from Alexa (it is located in .lambda/src/handlers/handler.js). Depending on the type of directive, this class routes the request to directive specific handlers. All directives are supported.

The Handler class contains a couple of additional directives that are specific to the reference project. As your web player might need to call your Lambda again while running on device, the following directives are supported as well:

UPDATE_VIDEO_PROGRESS supports video streaming by updating the last known timestamp. If users end their experience and resume streaming the same video later, they can pick up where they left off.
REFRESH_WEB_PLAYER_CREDENTIALS supports refreshing security IAM credentials for the web player before their expiration.

Customize the Number of Categories in Landing Page

Given the screen size of the device, display up to five categories on the landing page by changing the NUM_CATEGORIES_ON_LANDING_PAGE in ./lambda/utils/constants.js.

Next Steps

See Web Player Overview.

Last updated: Oct 29, 2020