Convertir les liens annexes en pièces jointes de modules complémentaires Classroom

Pour ajouter du contenu tiers dans Classroom, les enseignants peuvent par exemple coller un lien sous forme de pièce jointe "Link" sur la page de création du devoir. Pour approfondir les connaissances que les enseignants connaissent déjà, vous pouvez désormais configurer votre module complémentaire de sorte qu'il leur permette de convertir un rattachement Link en pièce jointe de module complémentaire.

Présentation

Si vous configurez votre module complémentaire avec cette fonctionnalité, les enseignants sont invités à mettre à niveau le lien vers la pièce jointe de module complémentaire lorsqu'ils collent une pièce jointe "Link" sur la page de création du devoir. Les enseignants ne sont invités à le faire que s'ils ont déjà installé le module complémentaire.

Une fois que l'enseignant accepte de mettre à jour le lien vers une pièce jointe de module complémentaire, l'iFrame de mise à niveau du lien est lancé avec les paramètres de requête suivants:

  • courseId
  • itemId (ancien nom : postId)
  • itemType (nouveau !)
  • addOnToken
  • login_hint ou hd
  • urlToUpgrade (nouveau !)

Les quatre premiers paramètres de requête reflètent ceux lancés dans l'iFrame Discovery de pièces jointes. Le paramètre de requête urlToUpgrade est nouveau et peut vous aider à évaluer la façon dont le rattachement de module complémentaire doit être créé. Vous pouvez ensuite utiliser les autres paramètres de requête pour vérifier si l'utilisateur est connecté et appeler la méthode CreateAddOnAttachment de courseWork, courseWorkMaterials ou announcements en fonction de la valeur itemType. Dans l'iFrame, vous pouvez afficher un écran de chargement pour indiquer à l'enseignant que la pièce jointe de module complémentaire est en cours de création.

Une fois la pièce jointe du module complémentaire créée, l'iFrame est fermé et l'enseignant peut l'afficher dans le devoir comme il le ferait habituellement.

Détails techniques de l'implémentation

Cette section présente certains détails techniques importants concernant cette fonctionnalité.

Lire le paramètre de requête urlToUpgrade

Le paramètre de requête urlToUpgrade est encodé en URI lorsqu'il est transmis dans l'iFrame de mise à niveau de lien. Vous devez décoder l'URL pour l'obtenir dans son format d'origine. Par exemple, si vous utilisez JavaScript, vous pouvez utiliser la fonction decodeURIComponent().

Pour garantir une expérience utilisateur optimale pour cette fonctionnalité, envoyez un postMessage une fois la pièce jointe de module complémentaire créée. L'iFrame se ferme. Pour en savoir plus, consultez la page d'informations sur l'implémentation d'un cadre iFrame.

Détails de la configuration

Les configurations suivantes sont requises pour intégrer cette fonctionnalité à votre module complémentaire:

  • URL de l'iFrame de mise à niveau du lien: il s'agit de l'URL qui s'ouvre dans l'iFrame lorsqu'un enseignant accepte de procéder à la mise à niveau.

  • Formats d'URL que Classroom doit détecter et tenter de mettre à niveau: les formats d'URL peuvent être constitués d'un hôte et de plusieurs préfixes de chemin d'accès.

    • Vous pouvez fournir plusieurs formats d'URL.
    • Si vous ne fournissez pas de préfixe de chemin, toute URL correspondant à l'hôte peut être mise à niveau.
    • Seules les URL avec un schéma https peuvent être mises à jour.
    • Les formats d'URL ne doivent pas contenir localhost.
    • Les préfixes de chemin d'accès ne doivent pas contenir de paramètres de requête ni de fragments d'URL.
    • Pour le moment, les préfixes de chemin d'accès acceptent les caractères génériques, mais les hôtes ne peuvent pas :
      • example.com est un hôte valide, et /foo et /bar/*/baz sont des préfixes de chemin valides.
      • example.*.host.com n'est pas un hôte valide.
    • Un caractère générique entre les composants du préfixe de chemin d'accès ne correspond qu'à un seul composant et non à plusieurs composants séparés par des barres obliques. Prenons l'exemple d'un format d'URL avec l'hôte example.com et le préfixe de chemin /bar/*/baz :
      • https://example.com/bar/123/baz est une correspondance valide pour le format d'URL.
      • https://example.com/bar/123/baz/456/789 est une correspondance valide pour le format d'URL.
      • https://example.com/bar/123/456/baz n'est pas une correspondance valide pour le format d'URL, car le caractère générique du préfixe de chemin ne correspond pas à /123/456/.

Processus de développement

Envoyez l'URL iFrame et les formats d'URL de mise à niveau de lien pour votre module complémentaire de test ou de production en envoyant un e-mail à l'adresse classroom-link-upgrade-external@google.com.

Vous pouvez d'abord fournir des configurations pour votre module complémentaire privé et pour tout environnement de test ou de développement dont vous êtes propriétaire. L'équipe Classroom peut activer ces configurations de test avant d'activer vos configurations de production afin que vous puissiez tester le flux dans votre domaine de démonstration. Vous recevrez une réponse à votre e-mail une fois les configurations activées. Notez que les formats d'URL qui utilisent localhost ne sont pas compatibles avec cette fonctionnalité.

Mettez en forme l'e-mail de façon à inclure les éléments suivants:

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

Remplacez les éléments suivants :

  • GCP_PROJECT_NUMBER: numéro du projet Google Cloud auquel le module complémentaire est associé.
  • LINK_UPGRADE_IFRAME_URL est l'URL qui doit s'ouvrir dans l'iFrame "Link Upgrade".
  • HOST_1: hôte que Classroom doit détecter. Seul le schéma https est accepté.
  • PATH_PREFIX_1 et PATH_PREFIX_2 : préfixes de chemin associés à HOST_1 que Classroom doit détecter et tenter de mettre à niveau.
  • HOST_2: hôte que Classroom doit détecter. Seul le schéma https est accepté.
  • PATH_PREFIX_3 et PATH_PREFIX_4 : préfixes de chemin associés à HOST_2 que Classroom doit détecter et tenter de mettre à niveau.

Vous trouverez ci-dessous des suggestions à prendre en compte lors de l'implémentation de cette fonctionnalité.

Éviter les tâches supplémentaires aux enseignants

Nous vous recommandons vivement d'utiliser l'iFrame pour faciliter la connexion, si nécessaire, ou pour afficher un indicateur de chargement. Pour une expérience utilisateur optimale, l'enseignant ne doit pas être invité à saisir d'informations supplémentaires après avoir accepté de convertir le lien collé en pièce jointe de module complémentaire. Toutefois, si cela n'est pas possible pour votre module complémentaire, vous pouvez utiliser l'iFrame de mise à niveau du lien pour recueillir les informations supplémentaires dont vous avez besoin. Le cadre iFrame permet également d'informer l'enseignant qu'il est impossible de mettre à jour le lien ou qu'une erreur s'est produite.

Inclure des messages d'erreur d'accès conviviaux

Si les enseignants collent et mettent à jour un lien auquel ils n'ont pas accès, affichez un message d'erreur convivial dans l'iFrame pour les informer du problème. Le cadre iFrame permet également d'accorder à l'enseignant les autorisations appropriées pour accéder au contenu.