Tutorial: Display a scene (basemap session) | CesiumJS

Learn how to use a basemap session to display a scene.

You can display satellite basemap tiles using basemap sessions. A basemap session is a time window (up to 12 hours) during which a user can access unlimited basemap tiles through an application. This means that instead of being charged for individual tile usage, you are only charged once per session. This usage model is especially cost-effective for 3D apps, where panning, zooming, and tilting the scene may load many tiles.

In this tutorial, display a scene using a basemap session that lasts for 12 hours.

Prerequisites

You need an ArcGIS Location Platform account.

ArcGIS Online and ArcGIS Enterprise accounts are not supported.

Steps

Create a new app

Create a new CodePen app with a map div that is the full width and height of the browser window.

Go to CodePen and create a new pen for your application.

In CodePen > HTML, add HTML and CSS to create a page with a div element called cesiumContainer.

Use dark colors for code blocks
<!DOCTYPE html>
<html lang="en">

  <head>

    <meta charset="utf-8">
    <title>CesiumJS: Display a Scene</title>

    <style>
    html,
    body,
    #cesiumContainer {
      margin: 0;
      padding: 0;
      width: 100%;
      height: 100%;
    }
    </style>
  </head>


  <body>

    <div id="cesiumContainer"></div>

  </body>

</html>

Set up authentication

Create a new API key credential with the correct privileges to access the resources used in this tutorial.

Go to the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
  - Location services > Basemaps > Basemap styles service

Add a <script> element in the HTML <body> and create an accessToken variable to store your access token. Set YOUR_ACCESS_TOKEN with the access token you previously copied from your API key credential.

Use dark colors for code blocks
    <script>

    /* Use for API key authentication */
    const accessToken = "YOUR_ACCESS_TOKEN";

    </script>

Get a Cesium ion access token

All Cesium applications must use an access token provided through Cesium ion. This token allows you to access assets such as Cesium World Terrain in your application.

Go to your Cesium ion dashboard to generate an access token. Copy the key to your clipboard.

Create a cesiumAccessToken variable and replace YOUR_CESIUM_ACCESS_TOKEN with the access token you copied from the Cesium ion dashboard.

Use dark colors for code blocks
    const accessToken = "YOUR_ACCESS_TOKEN";

    const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";

Configure Cesium.Ion.defaultAccessToken with the Cesium access token to validate the application.

Use dark colors for code blocks
    const accessToken = "YOUR_ACCESS_TOKEN";

    const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";

    Cesium.Ion.defaultAccessToken = cesiumAccessToken;

Add script references

You need to reference CesiumJS packages, as well as the ArcGIS REST JS arcgis-rest-basemap-sessions and arcgis-rest-request packages to use basemap sessions.

Add the following <link> and <script> references.

Use dark colors for code blocks
    <meta charset="utf-8">
    <title>CesiumJS: Display a scene (basemap session)</title>

    <!-- Load CesiumJS from cdn -->
    <script src="https://cesium.com/downloads/cesiumjs/releases/1.135/Build/Cesium/Cesium.js"></script>
    <link href="https://cesium.com/downloads/cesiumjs/releases/1.135/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
    <!-- Load ArcGIS REST JS from CDN -->
    <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-basemap-sessions@1/dist/bundled/basemap-sessions.umd.js"></script>

Create a session

Create a basemap session which can last for up to 12 hours or 43200 seconds. This allows you to access as many basemap tiles as you want for one basemap session charge.

Create an asynchronous function called createBasemapSession that starts a new BasemapStyleSession and returns it. Set the duration of the session to 43200 seconds (12 hours). Set autoRefresh to false to prevent the session from refreshing automatically.

Expand
Use dark colors for code blocks
    async function createBasemapSession() {
      const session = await arcgisRest.BasemapStyleSession.start({
        authentication: accessToken,
        styleFamily: "arcgis",
        duration: 43200, // 12 hours in seconds
        autoRefresh: false
      });

      return session;
    }
Expand

Create a scene

Use the session's token to load the ArcGisMapServerImageryProvider in a Viewer.

Declare the viewer and imageryProvider variables globally so they can be accessed later (e.g., when restarting the session). Set the basemap style to Cesium.ArcGisBaseMapType.SATELLITE.

Expand
Use dark colors for code blocks
    const basemapStyle = Cesium.ArcGisBaseMapType.SATELLITE;
    let viewer, imageryProvider;
Expand

Create a function called initApp that creates a basemap session and passes its token into Cesium.ArcGisMapService.defaultAccessToken. Call this function when the app starts.

Expand
Use dark colors for code blocks
    async function initApp() {

      const basemapSession = await createBasemapSession();
      const sessionToken = await basemapSession.getToken();
      Cesium.ArcGisMapService.defaultAccessToken = sessionToken;

    }

    initApp();
Expand

Create a new ArcGisMapServerImageryProvider using the basemap style declared earlier. This enumeration accesses the ArcGIS World Imagery base layer.

Expand
Use dark colors for code blocks
    async function initApp() {

      const basemapSession = await createBasemapSession();
      const sessionToken = await basemapSession.getToken();
      Cesium.ArcGisMapService.defaultAccessToken = sessionToken;

      imageryProvider = Cesium.ArcGisMapServerImageryProvider.fromBasemapType(basemapStyle);

    }

    initApp();
Expand

Create a Viewer attached to the cesiumContainer element. Create a new ImageryLayer from your imagery provider and set it as the baseLayer property. Set the camera's position and extent to the Santa Monica Mountains.

Expand
Use dark colors for code blocks
    async function initApp() {

      const basemapSession = await createBasemapSession();
      const sessionToken = await basemapSession.getToken();
      Cesium.ArcGisMapService.defaultAccessToken = sessionToken;

      imageryProvider = Cesium.ArcGisMapServerImageryProvider.fromBasemapType(basemapStyle);

      viewer = new Cesium.Viewer("cesiumContainer", {
        baseLayer: Cesium.ImageryLayer.fromProviderAsync(imageryProvider),
        terrain: Cesium.Terrain.fromWorldTerrain(),
        timeline: false,
        animation: false,
        geocoder: false
      });

      viewer.camera.setView({
        destination: Cesium.Cartesian3.fromDegrees(-118.705, 33.957, 35000),
        orientation: {
          heading: Cesium.Math.toRadians(0.0),
          pitch: Cesium.Math.toRadians(-70.0)
        }
      });

    }

    initApp();
Expand

Handle session expiration

To ensure your application always uses a valid session token, listen for basemap session events. You can refresh credentials when the session expires, and update the base layer when the session is refreshed.

Listen for the expired and refreshed events from the session. When the session expires, call refreshCredentials. When the session is refreshed, call applyToken to update the base layer. You will create the applyToken function in the next step.

Expand
Use dark colors for code blocks
    async function createBasemapSession() {
      const session = await arcgisRest.BasemapStyleSession.start({
        authentication: accessToken,
        styleFamily: "arcgis",
        duration: 43200, // 12 hours in seconds
        autoRefresh: false
      });

      session.on("refreshed", (e) => {
        applyToken(e.current.token);
      });

      session.on("expired", () => {
        session.refreshCredentials();
      });

      return session;
    }
Expand

Create a function called applyToken that updates the Cesium.ArcGisMapService.defaultAccessToken variable with the new session token. Then, remove the existing base layer and re-add it so that it uses the updated token.

Expand
Use dark colors for code blocks
    function applyToken(newToken) {
      Cesium.ArcGisMapService.defaultAccessToken = newToken;

      const baseLayer = viewer.imageryLayers.get(0);
      viewer.imageryLayers.remove(baseLayer, true);

      imageryProvider = Cesium.ArcGisMapServerImageryProvider.fromBasemapType(basemapStyle);
      viewer.imageryLayers.add(new Cesium.ImageryLayer.fromProviderAsync(imageryProvider), 0);
    }
Expand

Add attribution

You need to display Esri and data attribution in all applications that use Esri technology. CesiumJS displays data attribution automatically for the ArcGIS Basemap Styles service, however, you need to take additional steps to display Esri attribution ("Powered by Esri").

Create a new Credit for the Powered by Esri string with showOnScreen set to true and then add it to the viewer.

Expand
Use dark colors for code blocks
      // Add Esri attribution
      const poweredByEsri = new Cesium.Credit("Powered by <a href='https://www.esri.com/en-us/home' target='_blank'>Esri</a>", true);
      viewer.creditDisplay.addStaticCredit(poweredByEsri);
Expand

Run the app

Run the app.

The scene should display the ArcGIS World Imagery base layer using a basemap session. When the basemap session expires, the app refreshes the session and reapplies the basemap with the new token so the scene continues to work without interruption.

What's next?

Learn how to use additional location services in these tutorials:

Change the base layer

Change the imagery and terrain layers in a scene.

Add features as GeoJSON

Add features from a feature service to a scene.

Add 3D objects

Add 3D objects from a scene service to a scene.