Intermediate Tutorial


Getting Started with Amazon Sumerian, AWS Amplify, and the React Component


30 minutes

Posted on: January 4, 2019

Learn Sumerian
Getting Started with Amazon Sumerian, AWS Amplify, and the React Component

Tags

amplify
react
sumerian

In this tutorial you will learn about:


AWS Amplify recently added an XR category that has built-in support for Amazon Sumerian. Now, when you publish your Sumerian scene, you have the option to publish privately so that only authenticated users can access your scene.

In this tutorial, you will learn how to set up an AWS Amplify React app to hold a Sumerian scene for both authenticated and unauthenticated users to access. You will learn about the following:

  • AWS Amplify
  • React components

Prerequisites

Before you begin, you should have completed the following tasks:

Step 1: Publish the Sumerian Scene for Private Hosting

In this section you will publish your Sumerian scene for private access.

  1. Navigate to the Sumerian editor, choose Publish in the upper-right corner, and then choose Host privately.

    The scene will be published for private view. It generates a JSON config file for you to embed in your Amplify app.

  2. Choose Download JSON configuration. This downloads the JSON config file named sumerian_exports_ sceneId.json. Take note of the location of this file. We’ll copy it to our Amplify application src directory later in this tutorial.

Step 2: Set Up a React App with Amplify

The first thing to do is create a React app and add an Amplify project to it.

  1. Create the React app by using create-react-app.

     npx create-react-app sumerian-amplify-app
    
     # or
    
     create-react-app sumerian-amplify-app
    

    For more information about create-react-app, see this documentation.

  2. Change to the React project, and then install the aws-amplify and aws-amplify-react libraries.

     cd sumerian-amplify-app
    
     npm install aws-amplify aws-amplify-react --save
    

    Note: After the install succeeds, you may see some warnings populate. It is safe to ignore them.

  3. Now that the React project is created, initialize a new AWS Amplify project.

    If you need to install and configure the AWS Amplify CLI, follow the AWS Amplify Quickstart guide.

    With the Amplify CLI installed, you can initialize the cloud resources for our app.

     amplify init
    

    It will prompt you with a few questions, such as Enter a name for the project and Enter a name for the environment. Answer the questions accordingly. You can also have a different setup shown above, including using your own AWS account.

  4. Copy the sumerian_exports_ sceneId.json file you downloaded in Step 1. to the sumerian-amplify-app/src directory in and rename it to sumerian_exports.json.

  5. Next we need to provision cloud resources for our app. This include Amplify’s Authentication component.

     amplify add xr
    

    The CLI will prompt configuration options for the XR category such as a scene name identifier and the fullpath to the sumerian-amplify-app/src/sumerian_exports.json file from the previous step.

    When prompted, choose a friendly readable name for your scene and take note of it. This value will be used as an identifier for the scene when using the XR category in the framework.

    Amplify’s XR component will set up and utilize the Authentication category to setup scene authorization.

    Refer to the Amplify XR Component Documentation for more information.

  6. Now that we’ve added the Amplify Xr and Authentication components to the project, we need to provision the cloud resources for our app.
     amplify push
    

    This automatically provisions any required cloud resources for your application and generates a local aws-exports.js file in your local source directory containing identifiers to the provisioned resources.

  7. When the Amplify backend setup is finished, replace src/App.js with following code. This adds the configuation settings for the cloud resources you provisioned using the aws-exports.json file, adds the Sumerian scene you published using the sumerian_exports.json file, as well as updates the code to use ES6 Class Syntax. You also need to substitute the AWS region your Sumerian scene uses and the Friendly scene name you used in step 2.3 above.

     import React, {Component} from 'react';
     import './App.css';
     import { SumerianScene } from 'aws-amplify-react';
     import Amplify from 'aws-amplify';
     import Aws_exports from './aws-exports';
    
     Amplify.configure(Aws_exports);
    
     class App extends Component {
       render() {
         return (
           <div style={ { height: '100vh' } }>
             <SumerianScene sceneName='scene1'/>
           </div>
         );
       }
     };
    
     export default App;
    

    The SumerianScene component generates a default loading screen and default UI layout, including mute, full screen, and enter VR buttons.

    For more information about the React component, see this documentation.

  8. Test your React Web App.
     npm start
    

Step 3: Add User Authentication

The Amplify Xr Component created Identity Pools in Amazon Cognito as well as supporting authentication roles in the AWS Identity and Access Management (IAM) to support unauthenticated users (as you tested above), as well as authenticated users. For your own information, you can see the resources Amplify provisioned for you. For example, open the file amplify/backend/amplify-meta.json, search for the UnauthRoleName and copy the value into the copy buffer. Next open the IAM console in the AWS Management Console, choose Roles, and then search for the UnauthRoleName role you copied to the clipboard to see what Amplify set up on your behalf.

In this section we will add authenticated access to the React App so that the Sumerian scene can only be accessed by registered users.

  1. Configure the Amplify Auth Component.
     amplify update auth
    

    When prompted with What do you want to do?, choose Apply default configuration without Social Provider (Federation) and then press Enter to use the default configuration.

    This will create an Amazon Cognito User Pool for your app. As noted above, you can find the name of the user pool in amplify/backend/amplify-meta.json by searching for UserPoolName in the auth configuration section.

  2. Update your cloud resources.
     amplify push
    
  3. Update App.js to use the withAuthenticator Higher-Order Components (HOC) also from aws-amplify-react by replacing the default export at the bottom of the file.

     // at the top of App.js, replace the line `import { SumerianScene } from 'aws-amplify-react';` with this line
     import { withAuthenticator, SumerianScene  } from 'aws-amplify-react';
    
     // ...
    
     // at the bottom of App.js, replace the line `export default App;` with this line
     export default withAuthenticator(App, { includeGreetings: true });
    

    Your final App.js should look like this:

     import React, {Component} from 'react';
     import './App.css';
     import { withAuthenticator, SumerianScene  } from 'aws-amplify-react';
     import Amplify from 'aws-amplify';
     import Aws_exports from './aws-exports';
    
     Amplify.configure(Aws_exports);
    
     class App extends Component {
       render() {
         return (
           <div style={ { height: '100vh' } }>
             <SumerianScene sceneName='scene1'/>
           </div>
         );
       }
     };
    
     export default withAuthenticator(App, { includeGreetings: true });
    

    Now when you serve the app it will ask you for login details:

     npm start
    

    For more information about the Amplify Auth module, see the Amplify page here.

Step 4: Adjust Styles

In this section we’ll adjust CSS files so that scenes will be screen centered for all devices.

  1. Open src/index.css and add the body style and add a height: 100%; line to the existing html style:
     html {
       height: 100%;
     }
    
     body {
       height: 100%;
       ...
     }
    
    

    Your final index.css should look like this:

     body {
     margin: 0;
     font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen",
       "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
       sans-serif;
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
     height: 100%;
     }
    
     html {
     height: 100%;
     }
    
     code {
     font-family: source-code-pro, Menlo, Monaco, Consolas, "Courier New",
       monospace;
     }
    
  2. Open src/App.css and replace the .App style the following:
     .App {
       width: 100%;
       height: 100%;
       display: flex;
       justify-content: center;
       align-items: center;
     }
    

Step 5: Working with Other AWS Services

To access a specific AWS service, or if your scene contains a Host (using Amazon Polly), you have to explicitly include at least those services in your AWS Amplify app.

For example, to include Amazon Polly in your app:

import AWS from 'aws-sdk';

new AWS.Polly();

By default, JavaScript built tools such as webpack will strip out unused dependency components using a process called tree shaking. Your Sumerian scene is loaded dynamically by the browser at runtime, so webpack doesn’t know what JavaScript code is used for and will strip out AWS SDK clients not using in your Amplify app. Because the Sumerian scene will use the Amplify login credential, if you include a Host in your scene, you have to attach a policy for Amazon Polly to have access to your Amazon Cognito role also.

For more information, see this documentation.

Step 6: Running on a VR or AR Device

In this section you publish the React App to a URL and then browse to the URL using a VR headset.

  1. To publish the app, start by adding hosting to the Amplify project.

     amplify add hosting
    

  2. Choose DEV for hosting using an Amazon S3 bucket with HTTP, choose PROD for hosting with Amazon CloudFront using HTTPS (recommended), and keep the defaults for the rest of the options.

  3. Publish the app.

     amplify publish
    

    This publishes the app to a live URL. You can then open the URL in any browser, VR headset or AR device to try it out!

To learn more about AWS Amplify with XR, see the documentation.

Back to Tutorials

© 2019 Amazon Web Services, Inc or its affiliates. All rights reserved.