Les enseignants peuvent ajouter du contenu tiers dans Classroom en collant un lien en tant que pièce jointe de lien sur la page de création du devoir. Pour vous appuyer sur ce que les enseignants sont déjà familiarisés, vous pouvez désormais configurer votre module complémentaire pour 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 le collent sur la page de création d'un devoir. Les enseignants ne sont invités à le faire que s'ils ont déjà installé le module.
Une fois que l'enseignant accepte de mettre à niveau 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
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 l'iFrame de découverte de pièces jointes. Le paramètre de requête urlToUpgrade
est nouveau et peut vous aider à évaluer le mode de création de la pièce jointe de module complémentaire. 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 de module complémentaire créée, l'iFrame est fermé et l'enseignant peut voir la pièce jointe dans le devoir comme d'habitude.
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 sur l'iFrame de mise à niveau du lien. Vous devez décoder l'URL pour l'obtenir dans son format d'origine. Si vous utilisez JavaScript, par exemple, vous pouvez utiliser la fonction decodeURIComponent()
pour le faire.
Fermer l'iFrame de mise à niveau du lien
Pour garantir une expérience utilisateur optimale pour cette fonctionnalité, envoyez une postMessage
une fois la pièce jointe de module complémentaire créée. Cette action ferme l'iFrame. 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 l'iFrame lorsqu'un enseignant accepte d'effectuer la mise à niveau.
Formats d'URL que Classroom doit détecter et tenter de mettre à jour: 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 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 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 d'accès valides. -
example.*.host.com
n'est pas un hôte valide.
-
- Un caractère générique entre les composants de 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 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 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. Vous pourrez ainsi 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 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 l'iFrame de mise à niveau des liens.
- 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 à jour. - 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 à jour.
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 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é à fournir d'autres informations une fois qu'il a accepté de mettre à niveau 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 des liens pour collecter les informations supplémentaires dont vous avez besoin. L'iFrame peut également servir à informer l'enseignant si la mise à niveau du lien n'est pas possible 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, affichez un message d'erreur convivial dans l'iFrame afin d'informer les enseignants du problème. L'iFrame peut également être utilisé pour accorder à l'enseignant les autorisations appropriées pour accéder au contenu.