Criar um complemento do Google Sala de Aula

Este é o primeiro tutorial da série de tutoriais de complementos do Google Sala de Aula.

Neste tutorial, você criará as bases para desenvolver um aplicativo da Web e publicá-lo como um complemento do Google Sala de Aula. As próximas etapas do tutorial expandem esse app.

Neste tutorial, você vai:

• Crie um projeto do Google Cloud para seu complemento.
• Criar um esqueleto de app da Web com botões de login de marcador de posição.
• Publique uma página "Detalhes do app" do Google Workspace Marketplace para seu complemento.

Depois de terminar, você poderá instalar e carregar seu complemento no iframe de complementos do Google Sala de Aula.

Pré-requisitos

Escolha um idioma para ver os pré-requisitos apropriados:

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

Configure um projeto do Google Cloud

O acesso à API Classroom e aos métodos de autenticação obrigatórios são controlados pelos projetos do Google Cloud. As instruções a seguir mostram as etapas mínimas para criar e configurar um novo projeto para uso com seu complemento.

Criar o projeto

Acesse a página de criação de projetos para criar um novo projeto do Google Cloud. Você pode fornecer qualquer nome para o novo projeto. Clique em Criar.

A criação do novo projeto leva alguns instantes. Depois, selecione o projeto. Escolha-o no menu suspenso do seletor de projetos na parte superior da tela ou clique em SELECIONAR PROJETO no menu de notificações no canto superior direito.

Anexar o SDK do Google Workspace Marketplace ao projeto do Google Cloud

Acesse o navegador da Biblioteca de APIs. Pesquise Google Workspace Marketplace SDK. O SDK vai aparecer na lista de resultados.

Selecione o card "SDK do Google Workspace Marketplace" e clique em Ativar.

Configurar o SDK do Google Workspace Marketplace

O Google Workspace Marketplace fornece a listagem pela qual usuários e administradores instalam seu complemento. Configure a Configuração do app e a Listagem na loja do SDK do Marketplace e a Tela de consentimento do OAuth para continuar.

Configuração do app

Navegue até a página Configuração do aplicativo do SDK do Marketplace. Forneça as seguintes informações:

• Defina a Visibilidade do app como Public ou Private.

  • A configuração pública é destinada a apps que serão lançados para os usuários finais. Um app público precisa passar por um processo de aprovação antes de ser publicado para os usuários finais, mas é possível especificar usuários que podem instalá-lo e testá-lo como um rascunho. Este é um estado de pré-publicação que permite que você teste e desenvolva seu complemento antes de enviá-lo para aprovação.
  • A configuração particular é adequada para testes e desenvolvimento internos. Um app particular só pode ser instalado por usuários no mesmo domínio em que o projeto foi criado. Portanto, defina a visibilidade como particular apenas se o projeto tiver sido criado em um domínio com uma assinatura do Google Workspace for Education. Caso contrário, os usuários de teste não poderão iniciar os complementos do Google Sala de Aula.

• Defina Configurações de instalação como Admin Only install se quiser restringir a instalação aos administradores do domínio.

• Em Integração de apps, selecione Complemento do Google Sala de Aula. O URI de configuração de anexo secure será solicitado. Esse é o URL que você espera que seja carregado quando um usuário abrir o complemento. Para os fins deste tutorial, precisa ser https://<your domain>/addon-discovery.

• Os prefixos de URI de anexo permitidos são usados para validar os URIs definidos em AddOnAttachment usando os métodos courses.*.addOnAttachments.create e courses.*.addOnAttachments.patch. A validação é uma correspondência de prefixo de string literal e não permite o uso de caracteres curinga no momento. Adicione pelo menos o domínio raiz do servidor de conteúdo, como https://localhost:5000/ ou https://cdn.myedtech.com/.

• Adicione os mesmos escopos do OAuth fornecidos na tela de consentimento do OAuth na etapa anterior.

• Preencha os campos conforme apropriado para sua organização em Links do desenvolvedor.

Detalhes do app

Acesse a página Detalhes do app do SDK do Marketplace. Forneça as seguintes informações:

• Em App Details, adicione um idioma ou expanda o menu suspenso ao lado do idioma já listado. Forneça um nome e descrições para o aplicativo. Eles aparecerão na página "Detalhes do app" do Google Workspace Marketplace do seu complemento. Clique em Concluído para salvar.
• Escolha uma Categoria para o complemento.
• Em Recursos gráficos, forneça imagens para os campos obrigatórios. Eles podem ser alterados mais tarde e podem ser marcadores de posição por enquanto.
• Em Links de suporte, informe os URLs solicitados. Eles podem ser marcadores se você tiver definido a visibilidade do app como Particular na etapa anterior.

Se você definiu a visibilidade do app como Privada na etapa anterior, clique em PUBLICAR. Seu app fica disponível imediatamente para instalação. Se você definir a Visibilidade do app como Pública, adicione endereços de e-mail na área Testadores de rascunho para todos os usuários de teste e clique em Salvar rascunho.

Tela de permissão OAuth

A tela de consentimento do OAuth aparece quando os usuários autorizam o app pela primeira vez. Ela solicita que eles permitam que o app acesse as informações pessoais e da conta, conforme definido pelos escopos que você ativar.

Acesse a página de criação para a tela de consentimento do OAuth. Forneça as seguintes informações:

• Defina Tipo de usuário como Externo. Clique em Criar.
• Na próxima página, preencha os detalhes necessários do app e os dados de contato. Forneça todos os domínios que hospedam o app em Domínios autorizados. Clique em SALVAR E CONTINUAR.

• Adicione todos os escopos do OAuth exigidos pelo app da Web. Consulte o guia de configuração do OAuth para ver uma discussão aprofundada sobre escopos e a finalidade deles.

  É preciso solicitar pelo menos um dos escopos a seguir para que o Google envie o parâmetro de consulta login_hint. Uma explicação mais detalhada sobre esse comportamento está disponível no nosso Guia de configuração do OAuth:

  • https://www.googleapis.com/auth/userinfo.email (já incluído)
  • https://www.googleapis.com/auth/userinfo.profile (já incluído)

  Os escopos a seguir são específicos dos complementos do Google Sala de Aula:

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

  Inclua também outros escopos de API do Google exigidos dos usuários finais pelo app.

  Clique em SALVAR E CONTINUAR.

• Liste os endereços de e-mail das contas de teste na página Usuários de teste. Clique em SALVAR E CONTINUAR.

Confirme se as configurações estão corretas e volte ao painel.

Instalar o complemento

Agora você pode instalar seu complemento usando o link na parte superior da página Detalhes do app do SDK do Marketplace. Clique no URL do app na parte de cima da página para conferir a lista e escolha Instalar.

Criar um app da Web básico

Configurar um aplicativo da Web de estrutura com duas rotas. As próximas etapas do tutorial expandem esse aplicativo. Por enquanto, basta criar uma página de destino para o complemento /addon-discovery e uma página de índice fictícia / para o "site da empresa".

Implemente estes dois endpoints:

• /: mostra uma mensagem de boas-vindas e um botão para fechar a guia atual e o iframe do complemento.
• /addon-discovery: mostra uma mensagem de boas-vindas e dois botões: um para fechar o iframe do complemento e outro para abrir um site em uma nova guia.

Observe que estamos adicionando botões para criar e fechar janelas ou o iframe. Elas demonstram um método para colocar o usuário com segurança em uma nova guia para autorização no próximo tutorial.

Criar script utilitário

Crie um diretório static/scripts. Crie um novo arquivo addon-utils.js. Adicione as duas funções a seguir.

/**
 *   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',
  }, '*');
};

Criar rotas

Implemente os endpoints /addon-discovery e /.

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";
}

Testar o complemento

Inicie o servidor. Em seguida, faça login no Google Sala de Aula como um dos usuários do teste Professor. Acesse a guia Atividades e crie uma Atividade. Selecione seu complemento no seletor Complementos. O iframe é aberto, e o complemento carrega o URI de configuração de anexos que você especificou na página Configuração do app do SDK do Marketplace.

Parabéns! Está tudo pronto para a próxima etapa: fazer login de usuários com o SSO do Google.