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

Les enseignants peuvent ajouter du contenu tiers à Classroom en collant un lien en tant que pièce jointe de type "Lien" sur la page de création de devoirs. Pour vous appuyer sur ce que les enseignants connaissent déjà, vous pouvez désormais configurer votre module complémentaire pour leur permettre de remplacer une pièce jointe de type "Lien" par une pièce jointe de module complémentaire .

Présentation

Si vous configurez votre module complémentaire avec cette fonctionnalité, les enseignants sont invités à remplacer un lien par une pièce jointe de module complémentaire lorsqu'ils collent une pièce jointe de type "Lien" sur la page de création de devoirs. Cette invitation ne s'affiche que si le module complémentaire est déjà installé.

Une fois que l'enseignant a accepté de remplacer le lien par une pièce jointe de module complémentaire, l'iFrame "Remplacement de lien" s'ouvre avec les paramètres de requête suivants :

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (uniquement si l'utilisateur a déjà autorisé votre application)

Les quatre premiers paramètres de requête sont identiques à ceux lancés sur l' iFrame "Découverte des pièces jointes". Le paramètre de requête urlToUpgrade est nouveau et peut vous aider à évaluer comment la pièce jointe de module complémentaire doit être créée. Vous pouvez ensuite utiliser les autres paramètres de requête pour vérifier si l'utilisateur est connecté et appeler la CreateAddOnAttachment méthode 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 de module complémentaire créée, l'iFrame est fermé et l'enseignant peut afficher la pièce jointe dans le devoir comme d'habitude.

Détails techniques de l'implémentation

Cette section met en évidence certains détails techniques importants de la fonctionnalité.

Lire le paramètre de requête urlToUpgrade

Le paramètre de requête urlToUpgrade est encodé en URI lorsqu'il est transmis à l'iFrame "Remplacement de lien". Vous devez décoder l'URL pour l'obtenir dans sa forme d'origine. Si vous utilisez JavaScript, par exemple, vous pouvez utiliser la fonction decodeURIComponent() pour ce faire.

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 est alors fermé. Pour en savoir plus, consultez la page Détails de l'implémentation de l'iFrame.

Détails de la configuration

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

  • URL de l'iFrame "Remplacement de lien" : il s'agit de l'URL qui s'ouvre dans l' iFrame lorsqu'un enseignant accepte le remplacement.

  • Formats d'URL que Classroom doit détecter et tenter de remplacer : 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 aucun préfixe de chemin d'accès, toute URL correspondant à l'hôte peut être remplacée.
    • Seules les URL avec un schéma https peuvent être remplacées.
    • 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.
    • Les préfixes de chemin d'accès peuvent accepter les caractères génériques pour le moment, mais pas les hôtes :
      • example.com est un hôte valide, et /foo et /bar/*/baz sont des préfixes de chemin d'accès 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 d'accès /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 d'accès ne correspond pas à /123/456/.

Processus de développement

Envoyez l'URL de l'iFrame "Remplacement de lien" et les formats d'URL de votre module complémentaire de test ou de production par e-mail à l'adresse classroom-link-upgrade-external@google.com.

Vous pouvez fournir des configurations pour n'importe quel projet Google Cloud représentant un module complémentaire Classroom. Nous vous recommandons de commencer par fournir des configurations pour un module complémentaire avec une visibilité privée afin de pouvoir développer et tester dans un domaine de démonstration sans affecter les utilisateurs actifs.

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 : URL qui doit s'ouvrir dans l'iFrame " Remplacement de lien".
  • 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 d'accès associés à HOST_1 que Classroom doit détecter et tenter de remplacer.
  • 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 d'accès associés à HOST_2 que Classroom doit détecter et tenter de remplacer.

Voici quelques suggestions à prendre en compte lors de l'implémentation de cette fonctionnalité.

Éviter de surcharger le travail des enseignants

Nous vous recommandons vivement d'utiliser l'iFrame pour faciliter la connexion, si nécessaire, ou afficher un indicateur de chargement. Pour une expérience utilisateur optimale, l'enseignant ne doit pas être invité à fournir des informations supplémentaires après avoir accepté de remplacer le lien collé par une pièce jointe de module complémentaire. Toutefois, si cela n'est pas possible pour votre module complémentaire, vous pouvez utiliser l'iFrame "Remplacement de lien" pour collecter les informations supplémentaires dont vous avez besoin. L'iFrame peut également être utilisé pour informer l'enseignant si le remplacement du lien n'est pas possible ou si une erreur s'est produite.

Inclure des messages d'erreur d'accès faciles à comprendre

Si les enseignants collent et remplacent un lien auquel ils n'ont pas accès, affichez un message d'erreur facile à comprendre dans l'iFrame afin qu'ils soient informés du problème. L'iFrame peut également être utilisé pour fournir à l'enseignant les autorisations appropriées pour accéder au contenu.