Détails des cadres iFrame et des paramètres de requête

Les modules complémentaires Classroom sont chargés dans un iframe pour offrir à l'utilisateur final une expérience fluide et pratique. Il existe quatre types d'iframes distincts. Consultez les pages sur les iframes dans le répertoire "Parcours utilisateur" pour obtenir un aperçu de l'objectif et de l'apparence de chaque iframe.

Consignes de sécurité pour les iFrames

Les partenaires doivent suivre les bonnes pratiques du secteur pour sécuriser leur iframe. Pour protéger l'iframe, notre équipe chargée de la sécurité recommande les mesures suivantes:

Configuration de l'URI de l'iFrame

L'URI de configuration de la pièce jointe est chargé par l'iframe de découverte des pièces jointes. C'est là que les enseignants commencent à créer des pièces jointes de modules complémentaires dans un post Classroom. Vous pouvez le définir dans la console du projet Google Cloud. Définissez cet URI sur la page API et services > SDK Google Workspace Marketplace > Configuration de l'application de votre projet Google Cloud.

Configuration de l'URI de l'iFrame

Les préfixes d'URI pour autoriser les pièces jointes permettent de valider les URI définis dans AddOnAttachment à l'aide des méthodes *.addOnAttachments.create et *.addOnAttachments.patch. La validation correspond à une correspondance littérale du préfixe de la chaîne et n'autorise pas l'utilisation de caractères génériques pour le moment.

Paramètres de requête

Les iFrames transmettent des informations essentielles au module complémentaire sous forme de paramètres de requête. Il existe deux catégories de paramètres: les paramètres liés aux pièces jointes et les paramètres liés à la connexion.

Les paramètres liés aux pièces jointes fournissent au module complémentaire des informations sur le cours, le devoir, la pièce jointe du module complémentaire, le devoir rendu par l'élève et un jeton d'autorisation.

ID du cours

La valeur courseId est un identifiant du cours.

Inclus avec toutes les iFrames.

ID de l'article

La valeur itemId est un identifiant de l'Announcement.

CourseWork ou CourseWorkMaterial sur lequel cette pièce jointe est jointe.

Inclus avec toutes les iFrames.

Type d'élément

La valeur itemType identifie le type de ressource sur lequel

est en pièce jointe. La valeur de la chaîne transmise est "announcements", "courseWork" ou "courseWorkMaterials".

Inclus avec toutes les iFrames.

ID de la pièce jointe

La valeur attachmentId est un identifiant de la pièce jointe.

Inclus avec les iFrames teacherViewUri, studentViewUri et studentWorkReviewUri.

ID de l'envoi

La valeur submissionId est un identifiant du travail de l'élève, mais elle doit être utilisée avec attachmentId pour identifier le travail de l'élève pour un devoir particulier.

Inclus avec studentWorkReviewUri.

Jeton du module complémentaire

La valeur addOnToken est un jeton d'autorisation utilisé pour effectuer

addOnAttachments.create pour créer le module complémentaire.

Inclus avec l'iframe de découverte des pièces jointes et l'iframe de mise à niveau des liens.

URL à mettre à niveau

La présence de la valeur urlToUpgrade implique que le

L'enseignant a inclus une pièce jointe de lien dans le devoir et a accepté de la convertir en pièce jointe de module complémentaire. Si vous n'avez pas encore configuré cette fonctionnalité, consultez le guide sur la mise à niveau des liens vers les pièces jointes de modules complémentaires pour en savoir plus.

Inclus avec l'iFrame de mise à niveau du lien.

Le paramètre de requête login_hint fournit des informations sur l'utilisateur Classroom qui consulte la page Web du module complémentaire. Ce paramètre de requête est fourni dans l'URL src de l'iframe. Il est envoyé lorsque l'utilisateur a déjà utilisé votre module complémentaire pour réduire les difficultés de connexion des utilisateurs finaux. Vous devez gérer ce paramètre de requête dans l'implémentation de votre module complémentaire.

Indice de connexion

login_hint est un identifiant unique du compte Google de l'utilisateur.

un compte de service Google. Une fois que l'utilisateur s'est connecté à votre module complémentaire pour la première fois, le paramètre login_hint est transmis à chaque visite ultérieure de votre module complémentaire par le même utilisateur.

Le paramètre login_hint peut être utilisé de deux manières:

  1. Transmettez la valeur login_hint lors du flux d'authentification afin que l'utilisateur n'ait pas besoin de saisir ses identifiants lorsque la boîte de dialogue de connexion s'affiche. L'utilisateur n'est pas automatiquement connecté.
  2. Une fois l'utilisateur connecté, utilisez ce paramètre pour comparer la valeur à celle des utilisateurs que vous avez peut-être déjà connectés au module complémentaire. Si vous trouvez une correspondance, vous pouvez laisser l'utilisateur connecté et éviter d'afficher un flux de connexion. Si le paramètre ne correspond à aucun de vos utilisateurs connectés, invitez l'utilisateur à se connecter à l'aide d'un bouton de connexion Google.

Inclus avec toutes les iFrames.

IFrame de découverte des pièces jointes

Dimension Description
Obligatoire Oui
URI Fourni dans les métadonnées du module complémentaire
Paramètres de requête courseId, itemId, itemType, addOnToken et login_hint
Hauteur 80% de la hauteur de la fenêtre moins 60 pixels pour l'en-tête supérieur
Largeur 1 600 px maximum
90% de la largeur de la fenêtre lorsque la fenêtre mesure 600 px ou moins
80% de la largeur de la fenêtre lorsque la fenêtre mesure plus de 600 px

Exemple de scénario de détection d'une pièce jointe

  1. Un module complémentaire Classroom est enregistré dans Google Workspace Marketplace avec un URI de découverte d'attachement de https://example.com/addon.
  2. Un enseignant installe ce module complémentaire et crée une annonce, un devoir ou un contenu dans l'un de ses cours. Par exemple, itemId=234, itemType=courseWork et courseId=123.
  3. Lors de la configuration de cet élément, l'enseignant choisit le nouveau module complémentaire installé en tant que pièce jointe.
  4. Classroom crée un iFrame dont l'URL src est définie sur https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. L'enseignant effectue des tâches dans l'iFrame pour sélectionner une pièce jointe.
  5. Lors de la sélection d'une pièce jointe, le module complémentaire envoie un postMessage à Classroom pour fermer l'iframe.

IFrames teacherViewUri et studentViewUri

Dimension Description
Obligatoire Oui
URI teacherViewUri ou studentViewUri
Paramètres de requête courseId, itemId, itemType, attachmentId et login_hint
Hauteur 100% de la hauteur de la fenêtre moins 140 px pour l'en-tête supérieur
Largeur Largeur de la fenêtre de 100 %

IFrame studentWorkReviewUri

Dimension Description
Obligatoire Non (détermine s'il s'agit d'une pièce jointe de type activité)
URI studentWorkReviewUri
Paramètres de requête courseId, itemId, itemType, attachmentId, submissionId et login_hint
Hauteur 100% de la hauteur de la fenêtre moins 168 px pour l'en-tête supérieur
Largeur 100% de la largeur de la fenêtre moins la largeur de la barre latérale<> la barre latérale mesure 312 px lorsqu'elle est développée et 56 px lorsqu'elle est réduite

Dimension Description
Obligatoire Oui, si votre module complémentaire est compatible avec la mise à niveau des liens vers des pièces jointes de modules complémentaires.
URI Fourni dans les métadonnées du module complémentaire
Paramètres de requête courseId, itemId, itemType, addOnToken, urlToUpgrade et login_hint
Hauteur 80% de la hauteur de la fenêtre moins 60 pixels pour l'en-tête supérieur
Largeur 1 600 px maximum
90% de la largeur de la fenêtre lorsque la fenêtre mesure 600 px ou moins
80% de la largeur de la fenêtre lorsque la fenêtre mesure plus de 600 px
  1. Un module complémentaire Classroom est enregistré avec un URI de mise à niveau de lien de https://example.com/upgrade. Vous avez fourni les modèles de préfixe d'hôte et de chemin d'accès suivants pour les pièces jointes de lien que Classroom doit essayer de convertir en pièce jointe de module complémentaire :
    • L'hôte est example.com et le préfixe de chemin est /quiz.
  2. Un enseignant crée une annonce, un devoir ou un support de cours dans l'un de ses cours. Par exemple, itemId=234, itemType=courseWork et courseId=123.
  3. Un enseignant colle un lien, https://example.com/quiz/5678, dans la boîte de dialogue d'ajout de lien qui correspond à un format d'URL que vous avez fourni. L'enseignant est alors invité à convertir le lien en pièce jointe de module complémentaire.

  4. Classroom lance l'iFrame de mise à niveau du lien avec l'URL définie sur https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

  5. Vous évaluez les paramètres de requête transmis sur l'iFrame et appelez le point de terminaison CreateAddOnAttachment. Notez que le paramètre de requête urlToUpgrade est encodé en URI lorsqu'il est transmis dans l'iFrame. Vous devez décoder le paramètre pour l'obtenir dans sa forme d'origine. JavaScript, par exemple, propose la fonction decodeURIComponent().

  6. Une fois qu'une pièce jointe de module complémentaire a été créée à partir d'un lien, vous envoyez un postMessage à Classroom pour fermer l'iframe.

Fermer l'iFrame

L'iFrame peut être fermée à partir de l'outil d'apprentissage en envoyant un postMessage avec la charge utile {type: 'Classroom', action: 'closeIframe'}. Classroom n'accepte cette postMessage que depuis le nom d'hôte+port correspondant à l'URI d'origine ouvert.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

Fermer l'iFrame depuis l'iFrame

Le domaine+port de la page qui envoie l'événement postMessage doit être le même que celui de l'URI utilisé pour lancer l'iFrame, sinon le message est ignoré. Pour contourner ce problème, vous pouvez rediriger vers une page du domaine d'origine qui ne fait que renvoyer l'événement postMessage.

Fermer l'iFrame à partir d'un nouvel onglet

Les protections interdomaines empêchent cela de fonctionner. Une solution consiste à gérer vous-même les communications entre l'iframe et le nouvel onglet, et à laisser l'iframe être responsable de l'émission de l'événement de fermeture postMessage. En passant, le lien hypertexte "Ouvrir dans le nom du partenaire" est en cours de suppression afin que les utilisateurs ne créent plus d'onglets de cette manière dans un avenir proche.

Restrictions

Tous les iFrames sont ouverts avec les attributs de bac à sable suivants:

  • allow-popups
  • allow-popups-to-escape-sandbox
  • allow-forms
  • allow-scripts
  • allow-storage-access-by-user-activation
  • allow-same-origin

et la règle de fonctionnalité suivante :

  • allow="microphone *"

Sachez que le blocage des cookies tiers rend difficile le maintien d'une session connectée dans une iframe. Consultez https://www.cookiestatus.com pour connaître l'état actuel du blocage des cookies dans différents navigateurs. Bien entendu, ce problème n'est pas propre aux modules complémentaires Google Classroom et affecte tous les sites Web qui utilisent des iFrames tiers. De nombreux partenaires ont déjà rencontré ce problème.

Voici quelques solutions générales:

  • Ouvrez un nouvel onglet pour créer le cookie dans un contexte propriétaire. Certains navigateurs autorisent l'accès aux cookies créés dans le contexte first party dans un contexte tiers.
  • Demandez à l'utilisateur d'autoriser les cookies tiers. Ce n'est pas toujours possible pour tous les utilisateurs.
  • Concevoir des applications Web monopages qui ne s'appuient pas sur des cookies

D'autres restrictions concernant les cookies sont attendues dans les prochaines versions de navigateur. Envoyez des demandes de fonctionnalités pour indiquer à Google comment réduire l'effort requis par les partenaires.

Rendre les modules complémentaires visibles à l'aide d'expressions régulières d'URL

Les enseignants créent souvent des devoirs avec des liens joints. Pour promouvoir l'utilisation de votre module complémentaire, vous pouvez spécifier des expressions régulières correspondant aux URL des ressources auxquelles vous pouvez accéder dans votre module complémentaire. Lorsqu'un enseignant joint un lien correspondant à l'une de vos expressions régulières, une boîte de dialogue qu'il peut ignorer s'affiche pour l'inciter à essayer votre module complémentaire. La boîte de dialogue ne s'affiche que si le module complémentaire est déjà installé pour son compte.

Si vous souhaitez proposer ce comportement aux enseignants, fournissez-leur les expressions régulières appropriées. Si les expressions régulières que vous fournissez sont trop larges ou entrent en conflit avec un autre module complémentaire, elles peuvent être modifiées pour être plus restreintes ou distinctes.

Enseignant sélectionnant un rattachement de lien Figure 1 Enseignant sélectionnant une pièce jointe de lien pour un nouveau devoir.

Lien de collage pour les enseignants Figure 2 Enseignant collant un lien à partir d'une source tierce L'enseignant a déjà installé le module complémentaire Classroom tiers.

Boîte de dialogue de visibilité des expressions régulières Figure 3 Boîte de dialogue interactive présentée à l'enseignant lorsque le lien collé correspond à une expression régulière spécifiée par le développeur tiers.

Si un enseignant sélectionne "Essayer maintenant" dans le pop-up, comme illustré à la figure 3, il est redirigé vers l'iframe de découverte des pièces jointes de votre module complémentaire.