Intégration des sessions de streaming AppStream 2.0 - Amazon AppStream 2.0
PrérequisRecommandations et remarques sur l'utilisationÉtape 1 : Spécifier un domaine hôte pour les sessions de streaming AppStream 2.0 intégréesÉtape 2 : Créer une URL de streaming pour l'authentification des utilisateursÉtape 3 : Télécharger les fichiers AppStream 2.0 intégrésÉtape 4 : Configurer votre site web pour l'intégration d'AppStream 2.0Constantes, fonctions et événements pour les sessions de streaming AppStream 2.0 intégrées

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Intégration des sessions de streaming AppStream 2.0

Vous pouvez créer une expérience dynamique, interactive et personnalisée pour vos utilisateurs en intégrant une session de streaming AppStream 2.0 à votre site web. Les sessions de streaming AppStream 2.0 intégrées permettent aux utilisateurs d'interagir avec des modèles 3D, des cartes et des jeux de données directement à partir de votre site web. Par exemple, les utilisateurs peuvent consulter des instructions de formation ou des documents pédagogiques en même temps que leur session de streaming AppStream 2.0.

Prérequis

Pour intégrer une session de streaming AppStream 2.0 à un site Web, vous devez disposer des éléments suivants :

Recommandations et remarques sur l'utilisation

Tenez compte des recommandations et des remarques sur l'utilisation suivantes pour les sessions de streaming AppStream 2.0 intégrées.

  • Pour conserver un contrôle maximal sur l'expérience de streaming AppStream 2.0 intégrée pour vos utilisateurs, nous vous recommandons de configurer des URL de streaming de courte durée durant environ 5 secondes. Tout utilisateur peut inspecter le contenu d'une page web et afficher sa source. Cela inclut le modèle d'objet de document (DOM) et l'URL src (source) de l'iframe. Si l'URL est toujours valide lorsqu'un utilisateur la copie, celui-ci peut coller l'URL dans un onglet distinct du navigateur et diffuser la session avec l'interface utilisateur standard du portail AppStream 2.0, sans les options d'intégration.

  • Les sessions simultanées ne sont pas prises en charge lorsque des domaines personnalisés sont utilisés pour les sessions de streaming AppStream 2.0 intégrées. Des sessions simultanées se produisent lorsque les utilisateurs démarrent deux sessions de streaming AppStream 2.0 intégrées sur la même page web ou sur deux onglets de navigateur différents. Vous ne pouvez pas avoir un seul utilisateur avec des sessions simultanées, mais vous pouvez avoir plusieurs utilisateurs. Par exemple, un utilisateur se connecte à votre application, celle-ci génère une URL de streaming à transmettre au client (qui est considéré comme un utilisateur unique pour la facturation), un client charge l'URL de streaming et ce client est affecté à une instance AppStream au sein du groupe que vous avez spécifié.

Étape 1 : Spécifier un domaine hôte pour les sessions de streaming AppStream 2.0 intégrées

Pour intégrer une session de streaming AppStream 2.0 à une page web, mettez d'abord à jour votre pile pour spécifier le domaine dans lequel héberger la session de streaming intégrée. Il s'agit d'une mesure de sécurité pour s'assurer que seuls les domaines de site web autorisés peuvent intégrer des sessions de streaming AppStream 2.0. AppStream 2.0 ajoute le ou les domaines que vous spécifiez à l'en-tête Content-Security-Policy (CSP). Pour plus d'informations, consultez Content Security Policy (CSP) dans la documentation MDN Web Docs de Mozilla.

Pour mettre à jour votre pile afin de spécifier le domaine dans lequel héberger la session de streaming intégrée, utilisez l'une des méthodes suivantes :

  • Console AppStream 2.0

  • Action d'API EmbedHostDomains

  • Commande embed-host-domains de l'interface de ligne de commande AWS (AWS CLI)

Pour spécifier un domaine hôte à l'aide de la console AppStream 2.0, procédez comme suit.

  1. Ouvrez la console AppStream 2.0 à l'adresse https://console.aws.amazon.com/appstream2.

  2. Dans le volet de navigation de gauche, choisissez Piles, puis sélectionnez la pile qui vous intéresse.

  3. Choisissez Edit (Modifier).

  4. Développez Intégrer AppStream 2.0 (facultatif).

  5. Dans Domaines hôtes, spécifiez un domaine valide. Par exemple : training.example.com.

    Note

    Les sessions de streaming intégrées sont prises en charge uniquement via HTTPS [port TCP 443].

  6. Choisissez Mettre à jour.

Étape 2 : Créer une URL de streaming pour l'authentification des utilisateurs

Vous devez créer une URL de streaming pour authentifier les utilisateurs pour les sessions de streaming AppStream 2.0 intégrées. SAML 2.0 et les groupes d'utilisateurs ne sont actuellement pas pris en charge pour les sessions de streaming intégrées. Pour créer une URL de streaming, utilisez l'une des méthodes suivantes :

Configuration requise pour l'utilisation de domaines personnalisés

Que vous utilisiez des domaines personnalisés pour appliquer la marque de votre entreprise ou pour vous assurer que les sessions de streaming AppStream 2.0 intégrées fonctionnent avec des navigateurs qui bloquent les cookies tiers, les exigences de configuration sont les mêmes.

Pour les navigateurs web qui bloquent les cookies tiers, des domaines personnalisés sont requis. AppStream 2.0 utilise des cookies de navigateur pour authentifier les sessions de streaming et permet aux utilisateurs de se reconnecter à une session active sans être invités à fournir leurs informations d'identification de connexion à chaque fois. Par défaut, les URL de streaming AppStream 2.0 incluent appstream.com comme domaine. Lorsque vous intégrez une session de streaming dans votre site web, appstream.com est traité comme un domaine tiers. Par conséquent, les sessions de streaming peuvent être bloquées lorsque des navigateurs modernes sont utilisés car ils bloquent les cookies tiers par défaut.

Pour éviter que les sessions de streaming AppStream 2.0 intégrées ne soient bloquées dans ce scénario, procédez comme suit :

  1. Spécifiez un domaine personnalisé pour héberger vos sessions de streaming AppStream 2.0 intégrées.

    Lorsque vous configurez votre domaine personnalisé, assurez-vous que le domaine est un sous-domaine de la page web dans laquelle vous prévoyez d'intégrer AppStream 2.0. Par exemple, si vous mettez à jour votre pile pour spécifier training.example.com comme domaine hôte, vous pouvez créer un sous-domaine appelé content.training.example.com pour vos sessions de streaming intégrées.

  2. Créez une URL de streaming pour les sessions de streaming AppStream 2.0 intégrées qui utilisent le même sous-domaine personnalisé. Pour créer l'URL de streaming, utilisez l'action d'API CreateStreamingURL ou la commande create-streaming-url de l'interface de ligne de commande AWS. Vous ne pouvez pas utiliser la console AppStream 2.0 pour créer une URL de streaming dans ce scénario.

    Pour créer une URL de streaming pour les sessions de streaming AppStream 2.0 intégrées, dans l'URL, remplacez appstream2.région.aws.amazon.com par votre propre domaine.

    Par défaut, les URL de streaming AppStream 2.0 sont formatées comme suit :

    https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode

    Si votre sous-domaine est content.training.example.com, votre nouvelle URL de streaming suit le format suivant :

    https://content.training.example.com/authenticate?parameters=authenticationcode
    Note

    Lorsque vous créez un domaine personnalisé, vous pouvez utiliser ce domaine pour les sessions de streaming AppStream 2.0 intégrées uniquement dans la région AWS pour laquelle il a été configuré. Si vous envisagez de prendre en charge des domaines personnalisés dans plusieurs régions, créez un domaine personnalisé pour chaque région applicable. De même, les sessions de streaming intégrées sont prises en charge uniquement via HTTPS [port TCP 443].

  3. Ajoutez appstream-custom-url-domain à l'en-tête de la page web qui hébergera les sessions de streaming intégrées. Pour la valeur d'en-tête, utilisez le domaine que votre proxy inverse affiche pour les utilisateurs. Par exemple :

    Header name: appstream-custom-url-domain
Header value: training.example.com

    La définition d'un domaine personnalisé et la création d'une URL de streaming qui spécifie le même domaine permettent d'enregistrer les cookies en tant que cookies de première partie. Pour plus d'informations sur la configuration de domaines personnalisés à l'aide d'Amazon CloudFront, consulter Utilisation de domaines personnalisés avec AppStream 2.0.

Après avoir configuré un domaine personnalisé pour vos sessions de streaming AppStream 2.0 intégrées, si vos URL de streaming ne sont pas redirigées vers votre domaine personnalisé, ou si votre domaine personnalisé ne s'affiche pas correctement pour vos utilisateurs, consultez les rubriques de dépannage suivantes :

Étape 3 : Télécharger les fichiers AppStream 2.0 intégrés

Pour héberger des sessions de streaming AppStream 2.0 intégrées, vous devez télécharger et configurer le fichier JavaScript de l'API AppStream 2.0 fourni.

  1. Sur la page web Intégration d'AppStream 2.0 à votre site web, choisissez le lien de l'étape 1 pour télécharger le fichier .zip du kit d'intégration AppStream 2.0, appstream_embed_<version>.zip.

  2. Accédez à l'emplacement où vous avez téléchargé le fichier .zip et extrayez le contenu du fichier.

  3. Le contenu extrait du fichier comprend un dossier, appstream-embed. Outre les fichiers Copyright.txt et Third_Party_Notices.txt, ce dossier contient les deux fichiers suivants :

    • appstream-embed.js : fournit l'API AppStream 2.0 intégrée. Ce fichier JavaScript inclut les fonctions et les actions d'API permettant de configurer et de contrôler votre session de streaming AppStream 2.0 intégrée.

    • embed-sample.html : décrit comment utiliser l'API AppStream 2.0 intégrée pour initialiser une session de streaming, appeler des fonctions et écouter des événements. Cet exemple de fichier développe les informations de cette rubrique afin de fournir un exemple de cas d'utilisation pour les développeurs.

Étape 4 : Configurer votre site web pour l'intégration d'AppStream 2.0

Les sections suivantes fournissent des informations sur la configuration de votre page web pour héberger des sessions de streaming AppStream 2.0 intégrées.

Importation du fichier JavaScript appstream-embed

  1. Sur la page web où vous prévoyez d'intégrer la session de streaming AppStream 2.0, importez le fichier appstream-embed.js dans la page web en ajoutant le code suivant :

    <script type="text/javascript" src="./appstream_embed.js"> </script>

  2. Ensuite, créez un conteneur div vide. L'ID du conteneur div que vous définissez est transmis au constructeur d'intégration AppStream 2.0. Il est ensuite utilisé pour injecter un iframe pour la session de streaming. Pour créer le conteneur div, ajoutez le code suivant :

    <div id="appstream-container"> </div>

Initialisation et configuration de l'objet d'interface AppStream.Embed

Pour initialiser l'objet d'interface AppStream.Embed en JavaScript, vous devez ajouter du code qui crée un objet AppStream.Embed avec des options pour l'URL de streaming et la configuration de l'interface utilisateur. Ces options, ainsi que l'ID div que vous avez créé, sont stockés dans un objet appelé appstreamOptions.

L'exemple de code suivant montre comment initialiser l'objet d'interface AppStream.Embed.

var appstreamOptions = {
     sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode...',
     userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.TOOLBAR]}
 };
 appstreamEmbed = new AppStream.Embed("appstream-container", appstreamOptions);

Dans le code, remplacez sessionURL et userInterfaceConfig par vos propres valeurs.

Note

La valeur spécifiée pour userInterfaceConfig masque toute la barre d'outils AppStream 2.0. Cette valeur, qui est incluse à titre d'exemple, est facultative.

sessionUrl

URL de streaming que vous avez créée à l'aide de la console AppStream 2.0, de l'action d'API CreateStreamingURL ou de la commande create-streaming-url de l'interface de ligne de commande AWS. Ce paramètre n'est pas sensible à la casse.

Type : chaîne

Obligatoire : oui

userInterfaceConfig

Configuration qui génère l'état initial des éléments de l'interface utilisateur. La configuration est une paire clé-valeur.

La clé, AppStream.Embed.Options.HIDDEN_ELEMENTS, spécifie les objets de l'interface utilisateur qui sont initialement masqués lors de l'initialisation de la session de streaming AppStream 2.0 intégrée. Par la suite, vous pouvez renvoyer des objets masqués et visibles à l'aide du paramètre getInterfaceState.

La valeur est un tableau de constantes (boutons de barre d'outils). Pour obtenir la liste des constantes que vous pouvez utiliser, consultez Utilisation de l'option HIDDEN_ELEMENTS.

Type : mappage (clé:valeur)

Obligatoire : non

Exemples de masquage d'éléments dans l'interface utilisateur AppStream 2.0

Les exemples de cette section montrent comment masquer les éléments de l'interface utilisateur AppStream 2.0 aux utilisateurs au cours de leurs sessions de streaming AppStream 2.0 intégrées.

Exemple 1 : Masquer toute la barre d'outils AppStream 2.0

Pour empêcher les utilisateurs d'accéder à tout bouton de la barre d'outils AppStream 2.0 pendant les sessions de streaming intégrées, utilisez la constante AppStream.Embed.Elements.TOOLBAR. Cette constante vous permet de masquer tous les boutons de la barre d'outils AppStream 2.0.

var appstreamOptions = {
     sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode...',
     userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.TOOLBAR]}
 };

Exemple 2 : Masquer un bouton spécifique de la barre d'outils AppStream 2.0

Vous pouvez afficher la barre d'outils AppStream 2.0, tout en empêchant les utilisateurs d'accéder à un bouton spécifique de celle-ci pendant les sessions de streaming intégrées. Pour ce faire, spécifiez la constante du bouton que vous souhaitez masquer. Le code suivant utilise la constante AppStream.Embed.Elements.FILES_BUTTON pour masquer le bouton Mes fichiers. Cela empêche les utilisateurs d'accéder aux options de stockage persistant pendant les sessions de streaming intégrées.

var appstreamOptions = {
     sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode...',
     userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.FILES_BUTTON]}
 };

Exemple 3 : Masquer plusieurs boutons de la barre d'outils AppStream 2.0

Vous pouvez afficher la barre d'outils AppStream 2.0, tout en empêchant les utilisateurs d'accéder à plusieurs boutons de celle-ci pendant les sessions de streaming intégrées. Pour ce faire, spécifiez les constantes des boutons que vous souhaitez masquer. Le code suivant utilise les constantes AppStream.Embed.Elements.END_SESSION_BUTTON et AppStream.Embed.Elements.FULLSCREEN_BUTTON pour masquer les boutons End Session (Fin de session) et Fullscreen (Plein écran).

Note

Séparez chaque constante par une virgule, sans espace devant ou après.

var appstreamOptions = {
     sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode... (https://appstream2.region.aws.amazon.com/#/)',
     userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.END_SESSION_BUTTON,AppStream.Embed.Elements.FULLSCREEN_BUTTON]}
 };

Constantes, fonctions et événements pour les sessions de streaming AppStream 2.0 intégrées

Les rubriques suivantes fournissent des informations de référence sur les constantes, les fonctions et les événements que vous pouvez utiliser pour configurer des sessions de streaming AppStream 2.0 intégrées.

Les éléments suivants de l'interface utilisateur AppStream 2.0 peuvent être transmis à l'option de configuration HIDDEN_ELEMENTS lorsqu'une session de streaming AppStream 2.0 intégrée est initialisée.

Utilisation de l'option HIDDEN_ELEMENTS

Les éléments suivants de l'interface utilisateur AppStream 2.0 peuvent être transmis sous forme de constantes à l'option de configuration HIDDEN_ELEMENTS lorsqu'une session de streaming AppStream 2.0 intégrée est initialisée. 

AppStream.Embed.Elements.TOOLBAR
AppStream.Embed.Elements.FULLSCREEN_BUTTON
AppStream.Embed.Elements.END_SESSION_BUTTON
AppStream.Embed.Elements.TOOLBAR
AppStream.Embed.Elements.CATALOG_BUTTON
AppStream.Embed.Elements.WINDOW_SWITCHER_BUTTON
AppStream.Embed.Elements.FILES_BUTTON
AppStream.Embed.Elements.CLIPBOARD_BUTTON
AppStream.Embed.Elements.COPY_LOCAL_BUTTON
AppStream.Embed.Elements.PASTE_REMOTE_BUTTON
AppStream.Embed.Elements.SETTINGS_BUTTON
AppStream.Embed.Elements.STREAMING_MODE_BUTTON
AppStream.Embed.Elements.SCREEN_RESOLUTION_BUTTON
AppStream.Embed.Elements.REGIONAL_SETTINGS_BUTTON
AppStream.Embed.Elements.FULLSCREEN_BUTTON
AppStream.Embed.Elements.END_SESSION_BUTTON

Les trois éléments suivants peuvent être transmis sous forme de chaînes dans HIDDEN_ELEMENTS, plutôt que sous forme de constantes.

Chaîne Description
'adminCommandsButton' Lorsque vous êtes connecté à une instance Image Builder AppStream 2.0, le bouton Commandes d'administration s'affiche dans le coin supérieur droit de la barre d'outils AppStream 2.0. La transmission de cette chaîne dans HIDDEN_ELEMENTS masque le bouton Commandes d'administration.
'softKeyboardButton' Pendant les sessions de streaming AppStream 2.0 sur des appareils tactiles, les utilisateurs peuvent appuyer sur l'icône du clavier dans la barre d'outils AppStream 2.0 pour afficher le clavier à l'écran. La transmission de cette chaîne dans HIDDEN_ELEMENTS masque l'icône du clavier.
'keyboardShortcutsButton' Pendant les sessions de streaming AppStream 2.0 sur des appareils tactiles, les utilisateurs peuvent appuyer sur l'icône Fn de la barre d'outils AppStream 2.0 pour afficher les raccourcis clavier. La transmission de cette chaîne dans HIDDEN_ELEMENTS masque l'icône Fn.

Fonctions pour l'objet AppStream.Embed

Le tableau suivant répertorie les fonctions qui peuvent être exécutées sur l'objet AppStream.Embed.

Fonction Description
AppStream.Embed(containerId:string, options:object) Constructeur d'objet AppStream.Embed. Ce constructeur initialise et communique avec l'objet AppStream.Embed et il utilise un ID de conteneur div. L'ID est utilisé pour injecter l'iframe. Il injecte également un objet qui inclut les options de configuration pour appstreamOptions (sessionURL et HIDDEN_ELEMENTS).
endSession() Cette fonction met fin à la session de streaming, mais ne détruit pas l'iframe. Si vous spécifiez une URL de redirection, l'iframe tente de charger l'URL. Selon les en-têtes CORS de la page, l'URL peut ne pas se charger.
launchApp(appId:string) Cette fonction lance par programmation une application ayant l'ID d'application spécifié lors de la création de l'image.
launchAppSwitcher() Cette fonction envoie la commande AppSwitcher au portail AppStream 2.0. Cela déclenche la commande AppSwitcher sur l'instance.
getSessionState() Cette fonction renvoie un objet pour sessionStatus. Pour plus d'informations, consultez Événements pour les sessions de streaming AppStream 2.0 intégrées.
getUserInterfaceState()

Cette fonction renvoie un objet pour UserInterfaceState. L'objet contient les paires clé-valeur pour les éléments suivants :

sessionStatus : énumération d'état

sessionTerminationReason : chaîne

sessionDisconnectionReason : chaîne

Pour plus d'informations, consultez Événements pour les sessions de streaming AppStream 2.0 intégrées.
addEventListener(name, callback) Cette fonction ajoute une fonction de rappel à appeler lorsque l'événement spécifié est déclenché. Pour obtenir la liste des événements pouvant être déclenchés, consultez Événements pour les sessions de streaming AppStream 2.0 intégrées.
removeEventListener(name, callback) Cette fonction supprime le rappel pour les événements spécifiés.
destroy() Cette fonction supprime l'iframe et nettoie les ressources. Cette fonction n'affecte pas les sessions de streaming en cours.

Événements pour les sessions de streaming AppStream 2.0 intégrées

Le tableau suivant répertorie les événements qui peuvent être déclenchés pendant les sessions de streaming AppStream 2.0 intégrées.

Événement Données Description
AppStream.Embed.Events.SESSION_STATE_CHANGE

sessionStatus: State enumeration

sessionTerminationReason : chaîne

sessionDisconnectionReason : chaîne

Cet événement est déclenché lorsqu'un changement d'état de session se produit. L'événement inclut une carte des états qui ont changé. Pour récupérer l'état complet de la session, utilisez la fonction getSessionState().

Voici les états de session :

AppStream.Embed.SessionStatus.Unknown : la session n'a pas démarré et n'est pas réservée.

AppStream.Embed.SessionStatus.Reserved : la session est réservée mais n'a pas démarré.

AppStream.Embed.SessionStatus.Started : l'utilisateur s'est connecté à la session et a commencé le streaming.

AppStream.Embed.SessionStatus Disconnected  : l'utilisateur s'est déconnecté de la session.

AppStream.Embed.SessionStatus.Ended : la session a été marquée comme terminée ou expirée.
AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE

hiddenElements : tableau de chaînes

isFullscreen : valeur booléenne

isSoftKeyboardVisible : valeur booléenne

 Cet événement est déclenché lorsqu'un changement d'état de session se produit. L'événement inclut une carte des états qui ont changé. Pour récupérer l'état complet de la session, utilisez la fonction getSessionState().
AppStream.Embed.Events.SESSION_ERROR

errorCode : nombre

errorMessage : chaîne

 Cet événement est déclenché lorsque des erreurs se produisent au cours d'une session.

Exemples d'ajout d'écouteurs d'événements et de fin d'une session de streaming AppStream 2.0 intégrée

Les exemples de cette section montrent comment effectuer les opérations suivantes :

  • Ajouter des écouteurs d'événements pour les sessions de streaming AppStream 2.0 intégrées.

  • Mettre fin par programmation à une session de streaming AppStream 2.0 intégrée.

Exemple 1 : Ajouter des écouteurs d'événements pour les sessions de streaming AppStream 2.0 intégrées

Pour ajouter des écouteurs d'événements pour les modifications d'état de session, les modifications d'état de l'interface de session et les erreurs de session pendant les sessions de streaming intégrées, utilisez le code suivant :

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_STATE_CHANGE, updateSessionStateCallback);

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE, updateUserInterfaceStateCallback);

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_ERROR, errorCallback);

Dans cet exemple, AppStream.Embed.Events.SESSION_STATE_CHANGE, AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE et AppStream.Embed.Events.SESSION_ERROR sont des noms d'événements.

Les fonctions updateSessionStateCallback, updateUserInterfaceStateCallback et errorCallback sont celles que vous implémentez. Ces fonctions sont transmises à la fonction addEventListener et appelées lorsqu'un événement est déclenché.

Exemple 2 : Mettre fin par programmation à une session de streaming AppStream 2.0 intégrée

Pour mettre fin à une session de streaming AppStream 2.0 intégrée, utilisez la fonction suivante :

appstreamEmbed.endSession();