יצירת תוסף ל-Classroom

זהו המדריך הראשון בסדרת המדריכים על התוספים של Classroom.

במדריך הזה נסביר איך לפתח אפליקציית אינטרנט ולפרסם אותה כתוסף ל-Classroom. השלבים הבאים במדריך יפתחו את האפליקציה הזו.

במהלך המדריך הזה תלמדו:

• יוצרים פרויקט חדש ב-Google Cloud עבור התוסף.
• יוצרים אפליקציית אינטרנט בסיסית עם לחצני placeholder לכניסה.
• לפרסם דף מוצר של התוסף ב-Google Workspace Marketplace.

בסיום, תוכלו להתקין את התוסף ולטעון אותו ב-iframe של תוספי Classroom.

דרישות מוקדמות

בוחרים שפה כדי לראות את דרישות ההרשאה המתאימות:

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

הגדרת פרויקט ב-Google Cloud

הגישה ל-Classroom API ולשיטות האימות הנדרשות מבוקרת על ידי פרויקטים ב-Google Cloud. בהוראות הבאות מוסבר איך יוצרים ומגדירים פרויקט חדש לשימוש עם התוסף.

יצירת הפרויקט

כדי ליצור פרויקט חדש ב-Google Cloud, עוברים אל דף יצירת הפרויקט. אפשר לתת שם כלשהו לפרויקט החדש. לוחצים על יצירה.

יצירת הפרויקט החדש תימשך כמה רגעים. בסיום, חשוב לבחור את הפרויקט. אפשר לבחור אותו בתפריט הנפתח של בורר הפרויקטים בחלק העליון של המסך, או ללחוץ על SELECT PROJECT בתפריט ההתראות בפינה השמאלית העליונה.

צירוף ה-SDK של Google Workspace Marketplace לפרויקט ב-Google Cloud

עוברים לדפדפן API Library. מחפשים את Google Workspace Marketplace SDK. ערכת ה-SDK אמורה להופיע ברשימת התוצאות.

בוחרים את הכרטיס של ה-SDK של Google Workspace Marketplace ולוחצים על הפעלה.

הגדרת ה-SDK של Google Workspace Marketplace

Google Workspace Marketplace מספק את דף המוצר שבו משתמשים ואדמינים יכולים להתקין את התוסף. כדי להמשיך, מגדירים את הגדרת האפליקציה ואת רשימת האפליקציה בחנות ב-Marketplace SDK, וגם את מסך ההסכמה ל-OAuth.

הגדרת האפליקציה

עוברים לדף App Configuration (הגדרת האפליקציה) של ה-SDK של Marketplace. יש לספק את הפרטים הבאים:

• מגדירים את App Visibility (חשיפה של האפליקציה) ל-Public או ל-Private.

  • ההגדרה 'גלוי לכולם' מיועדת לאפליקציות שיושקו בסופו של דבר למשתמשי קצה. אפליקציה ציבורית חייבת לעבור תהליך אישור לפני שהיא תפורסם למשתמשי הקצה, אבל אתם יכולים לציין משתמשים שיכולים להתקין ולבדוק אותה כטיוטה. זהו מצב לפני הפרסום, שמאפשר לבדוק ולפתח את התוסף לפני ששולחים אותו לאישור.
  • ההגדרה הפרטית מתאימה לפיתוח ולבדיקה פנימיים. רק משתמשים מאותו דומיין שבו נוצר הפרויקט יכולים להתקין אפליקציה פרטית. לכן, צריך להגדיר את החשיפה כ'פרטית' רק אם הפרויקט נוצר בדומיין עם מינוי ל-Google Workspace for Education, אחרת משתמשי הבדיקה לא יוכלו להפעיל תוספים ל-Classroom.

• אם רוצים להגביל את ההתקנה לאדמינים של הדומיין, מגדירים את Installation Settings לערך Admin Only install.

• בקטע שילוב אפליקציות, בוחרים באפשרות תוסף Classroom. תתבקשו להזין את ה-URI המאובטח של הגדרת הקובץ המצורף. זוהי כתובת ה-URL שאתם מצפים שתיטען כשמשתמש יפתח את התוסף. לצורך המדריך הזה, הערך צריך להיות https://<your domain>/addon-discovery.

• התחיליות המותרות של URI לקובצי מצורף משמשות לאימות של כתובות ה-URI שמוגדרות ב-AddOnAttachment באמצעות השיטות courses.*.addOnAttachments.create ו-courses.*.addOnAttachments.patch. האימות הוא התאמה לתחילית של מחרוזת מילולית, ולא ניתן להשתמש בתווים כלליים לחיפוש בשלב זה. מוסיפים לפחות את הדומיין ברמה הבסיסית של שרת התוכן, כמו https://localhost:5000/ או https://cdn.myedtech.com/.

• מוסיפים את אותם היקפי הרשאות OAuth שצוינו במסך ההסכמה ל-OAuth בשלב הקודם.

• בשדה Developer Links, ממלאים את השדות בהתאם לארגון.

רישום חנות

עוברים לדף Store Listing ב-Marketplace SDK. יש לספק את הפרטים הבאים:

• בקטע פרטי האפליקציה, מוסיפים שפה או מרחיבים את התפריט הנפתח לצד השפה שכבר רשומה. נותנים שם לאפליקציה ומתארים אותה. הפרטים האלה יופיעו בדף המוצר של התוסף ב-Google Workspace Marketplace. לוחצים על סיום כדי לשמור.
• בוחרים קטגוריה לתוסף.
• בקטע נכסי גרפיקה, מספקים תמונות לשדות הנדרשים. אפשר לשנות אותם מאוחר יותר, בינתיים אפשר להשתמש בתוויות placeholders.
• בקטע Support Links, מזינים את כתובות ה-URL המבוקשות. אפשר להשתמש בתוויות placeholders אם הגדרתם את סטטוס החשיפה של האפליקציה ל-Private בשלב הקודם.

אם הגדרתם את 'הרשאות הגישה לאפליקציה' לפרטית בשלב הקודם, לוחצים על פרסום. האפליקציה תהיה זמינה להתקנה באופן מיידי. אם מגדירים את סטטוס החשיפה של האפליקציה כגלוי לכולם, מוסיפים כתובות אימייל של משתמשי הבדיקה באזור בודקי הטיוטה ולוחצים על שמירה של הטיוטה.

מסך הסכמה ל-OAuth

מסך ההסכמה של OAuth מופיע בפעם הראשונה שמשתמשים מאשרים את האפליקציה. הוא מאפשר להם לאפשר לאפליקציה לגשת למידע האישי ולפרטי החשבון שלהם, בהתאם להיקפים שאתם מפעילים.

עוברים לדף היצירה של מסך ההסכמה ל-OAuth. יש לספק את הפרטים הבאים:

• מגדירים את User Type (סוג המשתמש) כ-External (חיצוני). לוחצים על יצירה.
• בדף הבא, ממלאים את פרטי האפליקציה הנדרשים ואת פרטי הקשר. בקטע Authorized Domains (דומיינים מורשים), מציינים את כל הדומיינים שמארחים את האפליקציה. לוחצים על שמירה והמשך.

• מוסיפים את כל היקפי ההרשאות של OAuth הנדרשים לאפליקציית האינטרנט. במדריך להגדרת OAuth מוסבר בהרחבה על ההיקפים ועל המטרה שלהם.

  כדי ש-Google תשלח את פרמטר השאילתה login_hint, צריך לבקש לפחות אחד מההיקפים הבאים. הסבר מפורט יותר על ההתנהגות הזו זמין במדריך להגדרת OAuth:

  • https://www.googleapis.com/auth/userinfo.email (כבר כלול)
  • https://www.googleapis.com/auth/userinfo.profile (כבר כלול)

  ההיקפים הבאים ספציפיים לתוספים ל-Classroom:

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

  יש לכלול גם את כל היקפי הרשאות Google API שנדרשים לאפליקציה ממשתמשי הקצה.

  לוחצים על שמור והמשך.

• בדף משתמשי בדיקה, מציינים את כתובות האימייל של כל חשבונות הבדיקה. לוחצים על שמירה והמשך.

מוודאים שההגדרות נכונות וחוזרים למרכז הבקרה.

התקנת התוסף

עכשיו אפשר להתקין את התוסף באמצעות הקישור בחלק העליון של הדף Store Listing ב-Marketplace SDK. לוחצים על כתובת ה-URL של האפליקציה בחלק העליון של הדף כדי להציג את כרטיס המוצר, ואז בוחרים באפשרות התקנה.

פיתוח אפליקציית אינטרנט בסיסית

הגדרה של אפליקציית אינטרנט בסיסית עם שני מסלולים. בשלבים הבאים במדריך נרחיב את האפליקציה הזו, אז בינתיים פשוט יוצרים דף נחיתה לתוסף /addon-discovery ודף מדומה של דף הבית / עבור 'אתר החברה'.

מטמיעים את שתי נקודות הקצה הבאות:

• /: מוצגת הודעת פתיחה ולחצן לסגירת הכרטיסייה הנוכחית וגם מסגרת ה-iframe של התוסף.
• /addon-discovery: מוצגת הודעת פתיחה ושני לחצנים: אחד לסגירת ה-iframe של התוסף והשני לפתיחת אתר בכרטיסייה חדשה.

לתשומת ליבכם: אנחנו מוסיפים לחצנים ליצירה ולסגירה של חלונות או של ה-iframe. בשלב הבא נסביר איך להשתמש בהם כדי להעביר את המשתמש בבטחה לכרטיסייה חדשה לצורך הרשאה.

יצירת סקריפט כלי

יוצרים ספרייה static/scripts. יוצרים קובץ חדש addon-utils.js. מוסיפים את שתי הפונקציות הבאות.

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

יצירת מסלולים

מטמיעים את נקודות הקצה /addon-discovery ו-/.

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

בדיקת התוסף

מפעילים את השרת. לאחר מכן, נכנסים ל-Google Classroom בתור אחד ממשתמשי הבדיקה שלכם בתפקיד מורה. עוברים לכרטיסייה עבודות ויוצרים מטלה חדשה. בוחרים את התוסף הרצוי מבורר התוספים. ה-iframe נפתח והתוסף טוען את URI להגדרת הקובץ המצורף שציינתם בדף הגדרת האפליקציה של Marketplace SDK.

מעולה! עכשיו אפשר להמשיך לשלב הבא: כניסת משתמשים באמצעות Google SSO.