Les modules complémentaires Google Classroom sont désormais disponibles pour tous les développeurs. Pour en savoir plus, consultez la documentation sur les modules complémentaires.

Cette page a été traduite par l'API Cloud Translation.

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

Pour ajouter des contenus tiers dans Classroom, en collant un lien en tant que pièce jointe de lien sur la page de création du devoir. Pour compiler en fonction de ce que les enseignants connaissent, vous pouvez désormais configurer votre module complémentaire permettre aux enseignants de convertir une pièce jointe 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 un lien vers une pièce jointe de module complémentaire lorsqu'ils collent le lien dans la pièce jointe page de création d'un devoir. Les enseignants ne sont invités à le faire que s'ils ont déjà installer le module complémentaire.

Une fois que l'enseignant a accepté de mettre à jour le lien vers une pièce jointe de module complémentaire, le lien La mise à niveau de l'iFrame est lancée 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 reflètent les paramètres de requête lancés sur le iFrame de découverte de pièces jointes. Le paramètre de requête urlToUpgrade est nouveau et peut vous aidera à évaluer la façon dont la pièce jointe de module complémentaire doit être créée. Ensuite, vous pouvez utiliser autres paramètres de requête pour vérifier si l'utilisateur est connecté et appeler la méthode 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 du 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 il le ferait habituellement.

Détails de l'implémentation technique

Cette section présente des détails techniques importants concernant 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 au lien Mettre à niveau l'iFrame. Vous devez décoder l'URL pour l'obtenir dans son format d'origine. Si que vous utilisez JavaScript, par exemple, vous pouvez utiliser decodeURIComponent() pour ce faire.

Fermer l'iFrame de mise à niveau du lien

Pour garantir une expérience utilisateur optimale pour cette fonctionnalité, envoyez un postMessage une seule fois la pièce jointe de module complémentaire a bien été créée. Cette action ferme l'iFrame. Voir pour en savoir plus, consultez la page d'informations sur 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 de mise à niveau des liens: il s'agit de l'URL qui s'ouvre dans iFrame lorsqu'un enseignant accepte d'effectuer la mise à niveau.
Formats d'URL que Classroom doit détecter et tenter de détecter mise à niveau: les formats d'URL peuvent être composés d'un hôte et de plusieurs chemins d'accès. préfixes.
- Vous pouvez fournir plusieurs formats d'URL.
- Si vous ne fournissez aucun préfixe de chemin, toute URL correspondant à l'hôte peuvent être mises à 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 sont compatibles avec 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 des composants de préfixe de chemin ne correspond qu'à un seul et ne correspond pas à 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 l'URL. du modèle.
  - https://example.com/bar/123/baz/456/789 est une correspondance valide pour le paramètre Format d'URL.
  - https://example.com/bar/123/456/baz n'est pas une correspondance valide pour 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 de mise à niveau des liens et les formats d'URL pour votre test ou votre production en envoyant un e-mail à l'adresse classroom-link-upgrade-external@google.com.

Vous pouvez fournir des configurations pour tout projet Google Cloud représentant Module complémentaire Classroom. Nous vous recommandons de fournir d'abord d'un module complémentaire avec une visibilité privée, afin que vous puissiez développer et les tester dans un domaine de démonstration sans affecter les utilisateurs actifs.

Vous recevrez une réponse à votre e-mail lorsque les configurations auront été est activé. Notez que les formats d'URL qui utilisent localhost ne sont pas compatibles. .

Mettez en forme l'e-mail de manière à 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 le Mise à niveau de l'iFrame de lien.
HOST_1: hôte que Classroom doit détecter. Seuls les Le schéma https est compatible.
PATH_PREFIX_1 et PATH_PREFIX_2: chemin d'accès préfixes associés à HOST_1 que Classroom doit détecter et tenter de résoudre pour effectuer la mise à niveau.
HOST_2: hôte que Classroom doit détecter. Seuls les Le schéma https est compatible.
PATH_PREFIX_3 et PATH_PREFIX_4: chemin d'accès préfixes associés à HOST_2 que Classroom doit détecter et tenter de détecter pour effectuer la mise à niveau.

Expérience utilisateur recommandée

Vous trouverez ci-dessous des suggestions à prendre en compte lors de la mise en œuvre de cette fonctionnalité.

Éviter les tâches supplémentaires pour les enseignants

Nous vous recommandons vivement d'utiliser le cadre iFrame pour faciliter la connexion, si ou afficher un indicateur de chargement. Pour une expérience utilisateur optimale, le l'enseignant ne devrait pas être invité à fournir d'autres informations a accepté de remplacer le lien collé par une pièce jointe de module complémentaire. Toutefois, s'il s'agit impossible pour votre module complémentaire, vous pouvez utiliser l'iFrame de mise à niveau des liens pour collecter les informations supplémentaires dont vous avez besoin. L'iFrame peut également servir à informer enseignant s'il est impossible de mettre à jour le lien ou si 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, message d'erreur convivial dans l'iFrame afin que les enseignants soient au courant du problème. L'iFrame peut également être utilisé pour fournir à l'enseignant le code les autorisations d'accès au contenu.