Créer un module complémentaire Classroom

Il s'agit du premier tutoriel de la série de tutoriels sur les modules complémentaires Classroom.

Dans ce tutoriel, vous allez préparer le terrain pour développer une application Web et la publier en tant que module complémentaire Classroom. Les étapes suivantes du tutoriel développeront cette application.

Au cours de ce tutoriel, vous effectuerez les opérations suivantes :

• Créez un projet Google Cloud pour votre module complémentaire.
• Créez une application Web squelette avec des boutons de connexion factices.
• Publiez une fiche Play Store Google Workspace Marketplace pour votre module complémentaire.

Une fois terminé, vous pouvez installer votre module complémentaire et le charger dans l'iFrame des modules complémentaires Classroom.

Prérequis

Sélectionnez une langue pour afficher les prérequis appropriés :

python -m ensurepip --upgrade

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

cd flask/01-basic-app
pip install -r requirements.txt

npm install

java --version
./mvnw --version

java -version
mvnw.cmd --version

Configurer un projet Google Cloud

L'accès à l'API Classroom et aux méthodes d'authentification requises est contrôlé par les projets Google Cloud. Les instructions suivantes vous guident tout au long des étapes minimales à suivre pour créer et configurer un projet à utiliser avec votre module complémentaire.

Créer le projet

Créez un projet Google Cloud en accédant à la page de création de projet. Vous pouvez attribuer n'importe quel nom au nouveau projet. Cliquez sur Créer.

La création complète du nouveau projet prend quelques instants. Une fois terminé, veillez à sélectionner le projet. Vous pouvez le choisir dans le menu déroulant du sélecteur de projet en haut de l'écran ou cliquer sur SÉLECTIONNER UN PROJET dans le menu des notifications en haut à droite.

Associer le SDK Google Workspace Marketplace au projet Google Cloud

Accédez au navigateur de la bibliothèque d'API. Recherchez Google Workspace Marketplace SDK. Le SDK devrait apparaître dans la liste des résultats.

Sélectionnez la fiche du SDK Google Workspace Marketplace, puis cliquez sur Activer.

Configurer le SDK Google Workspace Marketplace

Google Workspace Marketplace fournit la fiche via laquelle les utilisateurs et les administrateurs installent votre module complémentaire. Configurez la configuration de l'application et la fiche Play Store du SDK Marketplace, ainsi que l'écran d'autorisation OAuth pour continuer.

Configuration de l'application

Accédez à la page Configuration de l'application du SDK Marketplace. Fournissez les informations suivantes :

• Définissez la visibilité de l'application sur Public ou Private.

  • Le paramètre public est destiné aux applications qui seront finalement mises à la disposition des utilisateurs finaux. Une application publique doit faire l'objet d'une procédure d'approbation avant d'être publiée pour les utilisateurs finaux, mais vous pouvez spécifier les utilisateurs qui peuvent l'installer et la tester en tant que brouillon. Il s'agit d'un état de prépublication qui vous permettra de tester et de développer votre module complémentaire avant de l'envoyer pour approbation.
  • Le paramètre privé convient aux tests et au développement internes. Une application privée ne peut être installée que par les utilisateurs du même domaine que celui dans lequel le projet a été créé. Vous devez donc définir la visibilité sur privée uniquement si le projet a été créé dans un domaine avec un abonnement Google Workspace for Education subscription. Sinon, vos utilisateurs test ne pourront pas lancer les modules complémentaires Classroom.

• Définissez les paramètres d'installation sur Admin Only install si vous souhaitez limiter l'installation aux administrateurs de domaine.

• Sous Intégration de l'application, sélectionnez Module complémentaire Classroom. Vous êtes invité à saisir l'URI de configuration de la pièce jointe sécurisée. Il s'agit de l'URL que vous prévoyez de charger lorsqu'un utilisateur ouvre votre module complémentaire. Pour les besoins de ce tutoriel, il doit s'agir de https://<your domain>/addon-discovery.

• Les préfixes d'URI pour autoriser les pièces jointes sont utilisés pour valider les URI définis dans AddOnAttachment à l'aide des méthodes courses.*.addOnAttachments.create et courses.*.addOnAttachments.patch. La validation est une correspondance de préfixe de chaîne littérale et n'autorise pas l'utilisation de caractères génériques pour le moment. Ajoutez au moins le domaine racine de votre serveur de contenu, tel que https://localhost:5000/ ou https://cdn.myedtech.com/.

• Ajoutez les mêmes champs d'application OAuth que ceux fournis dans votre écran d'autorisation OAuth à l'étape précédente.

• Remplissez les champs de manière appropriée pour votre organisation sous Liens du développeur.

Fiche Play Store

Accédez à la page de la fiche Play Store du SDK Marketplace. Fournissez les informations suivantes :

• Sous Détails de l'application, ajoutez une langue ou développez le menu déroulant à côté de la langue déjà listée. Fournissez un nom d'application et des descriptions. Ils s'affichent sur la page de la fiche Play Store Google Workspace Marketplace de votre module complémentaire. Cliquez sur OK pour enregistrer.
• Choisissez une catégorie pour votre module complémentaire.
• Sous Composants graphiques, fournissez des images pour les champs obligatoires. Vous pourrez les modifier ultérieurement. Pour le moment, vous pouvez utiliser des espaces réservés.
• Sous Liens d'assistance, fournissez les URL demandées. Vous pouvez utiliser des espaces réservés si vous avez défini la visibilité de l'application sur Privée à l'étape précédente.

Si vous avez défini la visibilité de l'application sur Privée à l'étape précédente, cliquez sur PUBLIER. Votre application est immédiatement disponible à l'installation. Si vous avez défini la visibilité de l'application sur Publique, ajoutez des adresses e-mail dans la zone Testeurs de brouillons pour tous les utilisateurs test, puis cliquez sur Enregistrer le brouillon.

Écran d'autorisation OAuth

L'écran d'autorisation OAuth s'affiche lorsque les utilisateurs autorisent votre application pour la première fois. Il leur demande d'autoriser votre application à accéder à leurs informations personnelles et de compte, comme indiqué par les champs d'application que vous activez.

Accédez à la page de création de l'écran d'autorisation OAuth. Fournissez les informations suivantes :

• Définissez le type d'utilisateur sur Externe. Cliquez sur Créer.
• Sur la page suivante, remplissez les informations obligatoires sur l'application et les coordonnées. Fournissez tous les domaines qui hébergent votre application sous Domaines autorisés. Cliquez sur ENREGISTRER ET CONTINUER.

• Ajoutez tous les champs d'application OAuth dont votre application Web a besoin. Consultez le guide de configuration OAuth pour une discussion approfondie sur les champs d'application et leur objectif.

  Vous devez demander au moins l'un des champs d'application suivants pour que Google envoie le paramètre de requête login_hint. Vous trouverez une explication plus détaillée de ce comportement dans notre guide de configuration OAuth :

  • https://www.googleapis.com/auth/userinfo.email (déjà inclus)
  • https://www.googleapis.com/auth/userinfo.profile (déjà inclus)

  Les champs d'application suivants sont spécifiques aux modules complémentaires Classroom :

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

  Incluez également tous les autres champs d'application de l'API Google dont votre application a besoin auprès des utilisateurs finaux.

  Cliquez sur ENREGISTRER ET CONTINUER.

• Répertoriez les adresses e-mail de tous les comptes de test sur la page Utilisateurs test. Cliquez sur ENREGISTRER ET CONTINUER.

Vérifiez que vos paramètres sont corrects, puis revenez au tableau de bord.

Installer le module complémentaire

Vous pouvez maintenant installer votre module complémentaire à l'aide du lien en haut de la page de la fiche Play Store du SDK Marketplace. Cliquez sur Afficher dans Marketplace en haut de la page pour afficher la fiche, puis sélectionnez Installer.

Créer une application Web de base

Configurez une application Web squelette avec deux routes. Les étapes suivantes du tutoriel développeront cette application. Pour le moment, créez simplement une page de destination pour le module complémentaire /addon-discovery et une page d'index factice / pour le "site de notre entreprise".

Implémentez ces deux points de terminaison :

• /: affiche un message de bienvenue et un bouton permettant de fermer à la fois l'onglet actuel et l'iFrame du module complémentaire.
• /addon-discovery: affiche un message de bienvenue et deux boutons : l'un pour fermer l'iFrame du module complémentaire et l'autre pour ouvrir un site Web dans un nouvel onglet.

Notez que nous ajoutons des boutons pour créer et fermer des fenêtres ou l'iFrame. Ils illustrent une méthode permettant d'ouvrir en toute sécurité un nouvel onglet pour l'autorisation dans le prochain tutoriel.

Créer un script utilitaire

Créez un répertoire static/scripts. Créez un fichier addon-utils.js. Ajoutez les deux fonctions suivantes.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Créer des routes

Implémentez les points de terminaison /addon-discovery et /.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

import org.springframework.web.bind.annotation.GetMapping;

@org.springframework.stereotype.Controller
public class Controller {

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Tester le module complémentaire

Lancez votre serveur. Connectez-vous ensuite à Google Classroom en tant qu'utilisateur test Enseignant. Accédez à l'onglet Travaux et devoirs , puis créez un devoir. Sélectionnez votre module complémentaire dans le sélecteur Modules complémentaires. L'iFrame s'ouvre et le module complémentaire charge l'URI de configuration de la pièce jointe que vous avez spécifié sur la page de configuration de l'application du SDK Marketplace.

Félicitations ! Vous êtes prêt à passer à l'étape suivante : connecter les utilisateurs avec l'authentification unique Google.