はじめての Zoom Apps #QiitaEngineerFesta2022

■ 前置き

Zoom Appsは、Zoomクライアントの中へZoomが提供されるサービス以外のソリューションとを連携させるインターフェースが提供され、Zoomミーティング中またはミーティング外で利用いただけるよう用意されています。 ZoomAppsは個人用（アカウント内ユーザ）にて実装いただけますが、Zoom Maketplaceへ開示承認申請をいただくと、アカウントに関係なくすべてのZoomユーザーでご利用いただけるよう公開することも可能です。

今回、ZoomAppsを経由したZoomクライアント内のUI/UXでミーティング中に自身の人物映像と背景画像を合成させるサンプルを説明しています。（2022/12）

Zoom Apps の特徴

ZoomAppsからミーティング中のUXの操作が可能
Zoomクライアント内Webviewを経由した連携になるためWebサーバの用意が必要
提供するWebサービスは「OWASP(Open Web Application Security Project)」ヘッダーを使用する必要がある
接続しているユーザの識別やミーティングへの接続時状況はクライアントがアクセスする際に「X-Zoom-App-Context」ヘッダー内でサーバ側へ通知される

■ 実装前の準備について

１. https://marketplace.zoom.us/ へサインインします。
２. 右上プルダウンより「Build App」をクリック

３. 「Zoom Apps」タイルの中の「Create」で登録を進めていきます。

４. 「Create a Zoom app」の項目で必要となる以下項目を入力して「Create」で進みます。

App Name　: ここでは「Workshop Zoom Apps」としています
Distribution　: ここでは同じアカウント内のユーザのみの利用を目的とするため無効としています

５. 「App credentials」の項目で必要となる以下項目を入力して「Continue」で進みます。

Home URL : ZoomAppsで用意されたWebインターフェースからユーザがアクセスするサイトURL
Redirect URL for OAuth : ユーザが連携の利用開始をする際の認証ランディングURL
Add allow lists : 提供するWebサーバのURLを指定
Domain allow list : 上記に含まれないドメインを使用する場合には指定（ZoomAppsSDKをCDN経由で使用する場合には「appssdk.zoom.us」を指定）

６. 「Information」の項目で必要となる以下項目を入力して「Continue」で進みます。

Short description : 実装の目的について詳細を端的に入力
Long description : 実装の目的について詳細を具体的に入力
Company Name : 会社名または所属団体名を入力
Name : 名前を登録を入力
Email address : Zoomから重要な仕様変更の情報などご連絡させていただく際に利用されます。

７. 「Feature」の項目で必要となる項目を選択、設定して「Continue」で進みます。

Event Sunscription : 今回は実装にWebhookを含めないため無効としています。
Zoom Apps SDK : 連携で必要となる機能を選択します。ここでは必要となる下記を有効にして「Done」で設定します。
　　　　・setVirtualBackground
　　　　・removeVirtualBackground
　　　　・setVirtualForeground
　　　　・removeVirtualForeground
Guest mode : Zoomミーティングへゲスト接続しているユーザへも利用を許可するかの設定になります。ここでは有効にしています。
In-client OAuth : 今回は実装されたZoomAppsの利用中にZoomApps以外のZoom APIの利用を目的としていないので無効にしています。
Collaborate mode : ミーティング参加者とインタラクティブなUXを実現するための機能になりますが今回は無効にしています。

８. 「Scopes」ではZoom Apps以外のAPI利用においての権限項目を選択できますが、今回は「In-client OAuth」を無効としていますのでデフォルトのまま「Continue」で進みます。

９. 「Activation」の「Add」、「Add URL」は連携実装が完了後、実際の連携動作を確認する際に使用しますのでここで一旦準備完了となります。

■ Webサーバ側の実装について - サーバ・サイド

以下Node.jsの環境で解説していきます。

１. ファイル名で「index.js」でWebサーバを用意していきます。

const express = require('express')
const bodyParser = require('body-parser')
const cors = require('cors')
const crypto = require("crypto")
const app = express()
const port = 4601
const path = require('path')

２. フォルダ名「public」内にクライアントからアクセスするファイルを用意していくので、公開場所を指定します。

app.use(express.static(path.join(__dirname, 'public')))
app.use(bodyParser.json(), cors())

３. クライアントからアクセスされた際に全てOWASP対応にする必要があるので制限事項を明示します。

app.use(function(req, res, next) {
  res.header('Strict-Transport-Security', 'max-age=63072000')
  res.header('X-Content-Type-Options', 'nosniff')
  res.header(
    'Content-Security-Policy',
    "default-src *; \
    img-src * data:; \
    media-src *; \
    connect-src *; \
    script-src 'self' 'unsafe-inline' *; \
    style-src 'self' 'unsafe-inline' *;"
  )
  res.header('Referrer-Policy', 'same-origin')
  next()
})

４. クライアントがこのZoomAppsを使用許可を得た後のランディングページを明示します。Marketplaceでの登録の際に指定した「Redirect URL for OAuth」に相当します。ZoomとのOAuth認証を得てクライアントに代わりAPI操作を必要とする際にはここでOAuth実装となりますが、今回はクライアント完結型の実装になるので以下のように受け流す形で実装しています。

app.get('/oauth', (req, res) => {
  if(req.query.code){
    console.log("code: " + req.query.code);
  }
  var htmlbody = '<html><body>' +
                '<h1>Thank you</h1>' +
                '</body></html>'
  res.status(200)
  res.send(htmlbody)
  res.end()
})

５. 起動指定してサーバ側は完了です。

app.listen(port, () => console.log(`ZoomApps Sample. port: ${port}!`))

■ Webサーバ側の実装について - クライアント・サイド

サーバ・サイドで用意した「public」フォルダにクライアントに提供されるファイルを用意していきます。

１. ファイル名「public/index.html」でクライアント側のランディングページを用意します。
今回CDNを使用しているため「sdk.min.js」はCDNの矛先になっています。CDNを使用する際にはMarketplaceの登録時に「Domain allow list」に「appssdk.zoom.us」を明示指定する必要があります。
この後個別に指定している「style.css」、「myzoomapps.js」はこの後の実際の実装のため明示しています。

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <link href="css/style.css" rel="stylesheet" type="text/css">
</head>
<body>
<table><tr><th>
<h3>ZoomApps Sample</h3>
<hr />
<p>
 <canvas id="myCanvas" width="1280" height="720" style="border:1px solid #d3d3d3;"></canvas>
</p>
<p>
Preview:<br>
 <img id='image' style="border:1px solid #d3d3d3;">
</p>
<p>
 <input type="text" id="text" name="text">
</p>
<p>
 <button type="button" onclick="setVirtualForeground()">setVirtualForeground()</button>
 <br>
 <button type="button" onclick="removeVirtualForeground()">removeVirtualForeground()</button>
 <br>
 <button type="button" onclick="setVirtualBackground()">setVirtualBackground()</button>
 <br>
 <button type="button" onclick="removeVirtualBackground()">removeVirtualBackground()</button>
</p>
<hr />
</th></tr></table>
<b>Console Log:</b><br>
<p id="console"></p>
  <script src="https://appssdk.zoom.us/sdk.min.js"></script>
  <script src=".js/myzoomapps.js"></script>
</body>
</html>

２. 「myzoomapps.js」では最初にZoomAppsを使用するためにイニシャライズ(初期化)から始めます。
この際に使用するZoomAppsのAPIも明示する必要があるためここでは「setVirtualBackground」を明示しています。
また、CDNを使用する場合には「version」の指定も必要となります。ここでは「0.16」としています。

const start = async function(a, b) {
  const result = await zoomSdk.config({
    version: '0.16',
    capabilities: [
      "setVirtualBackground"
    ],
  });
  console.log(result);
}
start();

３. 続けて実際の挙動を追記していきます。今回はhtml内に配置したキャンバスを編集した画像を背景に合成する仕組み（setVirtualBackground）の他に、半透明な画像処理をすることで人物映像を背景にし編集画像を前面に表示する(setVirtualForeground)を含めています。

var c = document.getElementById("myCanvas");
var ctx = c.getContext("2d");
var image = document.getElementById('image'); //Image element

//Box
var imgData = ctx.createImageData(300, 150);
var i;
for (i = 0; i < imgData.data.length; i += 4) {
  //from 0-255; 0 is transparent and 255 is fully visible
  imgData.data[i+0] = 40; // red
  imgData.data[i+1] = 40; // green
  imgData.data[i+2] = 40; // blue
  imgData.data[i+3] = 40; // alpha channel
}

drawing = new Image();
drawing.src = "images/logo.png"; // can also be a remote URL e.g. http://

drawing.onload = function() {
  ctx.clearRect(0, 0, c.width, c.height);      // clear canvas
  ctx.putImageData(imgData, 0, 0);             // Box
  ctx.drawImage(drawing,0,82);                 // image size 300x68 canvas size 300x150 | 82 = 150-68
  image.src = ctx.canvas.toDataURL();          // add image on to img tag
  ctx.drawImage(image, 0, 0 );                 // draw inside img tag
  //console.log(image.src);
}

document.getElementById('text').addEventListener('keyup', function (){
    ctx.clearRect(0, 0, c.width, c.height); // clear canvas
    ctx.putImageData(imgData, 0, 0);
    ctx.drawImage(drawing,0,82);
    //ctx.fillStyle = 'white';
    ctx.font = "bold 60px verdana, sans-serif";
    ctx.fillText(this.value, 0, 60);
    image.src = ctx.canvas.toDataURL();
    //console.log(image.src);
    console.log("keyup:" + this.value);
}, false);

const FIXED_WIDTH = 1280;

async function getImageData(fileUrl) {
  return new Promise((resolve) => {
    const canvas = document.createElement('canvas')
    const img = new Image()
    img.crossOrigin = 'Anonymous'

    img.onload = function () {
      const height = (FIXED_WIDTH * img.height) / img.width

      canvas.width = FIXED_WIDTH
      canvas.height = height

      const ctx = canvas.getContext('2d')

      ctx.drawImage(img, 0, 0, FIXED_WIDTH, height)
      const imageData = ctx.getImageData(0, 0, FIXED_WIDTH, height)

      resolve(imageData)
    }

    img.src = fileUrl
  })
}

var imageid;

async function setVirtualForeground(){
   var imgdata = await getImageData(image.src);

   var myOptions = {
     imageData: imgdata
   };

   console.log("setVirtualForeground");
   imageid = await zoomSdk.setVirtualForeground(myOptions)
   .then((r) => {
       console.log("setVirtualForeground", r);
   })
   .catch((e) => {
       console.log("setVirtualForeground", e);
   });
}

async function removeVirtualForeground() {
    await zoomSdk.callZoomApi("removeVirtualForeground")
    .then(function(r){
      console.log("removeVirtualForeground", r);
    })
    .catch(function(e){
      console.log("removeVirtualForeground",e);
    })
}

async function setVirtualBackground(){
  console.log("setVirtualBackground");
  var myOptions = {
    fileUrl: image.src
  };
  await zoomSdk.setVirtualBackground(myOptions);
}

async function removeVirtualBackground() {
    await zoomSdk.callZoomApi("removeVirtualBackground")
    .then(function(r){
      console.log("removeVirtualBackground", r);
    })
    .catch(function(e){
      console.log("removeVirtualBackground",e);
    })
}

■ 動作確認

実際に動作確認をするためには、まず「Add」、「Add URL」のいずれかを使用して実装したZoomAppsを使用できるようにします。この際に使用するZoomユーザは同じアカウント内に所属しているユーザを利用する必要があります。

■ 実装にあたっての補足事項

開発コンソールへのアクセスについて
ZoomAppsを利用するクライアント側では開発ツールの利用を制限しているためコンソールログ等を参照することはできません。ただし、クライアント側で明示することで参照できるようにすることができます。取り扱いには注意ください。
詳しくはこちらを参照くださ。https://marketplace.zoom.us/docs/zoom-apps/create-zoom-app/

「X-Zoom-App-Context」ヘッダーについて
サーバ側で誰がアクセスしてきているのかなどヘッダーに含まれる「X-Zoom-App-Context」にて確認していただくことも可能です。
詳しくはこちらを参照ください。https://marketplace.zoom.us/docs/zoom-apps/zoomappcontext/

実装例

app.use(function(req, res, next) {
  var zoomAppContext = req.headers["x-zoom-app-context"];
  if(zoomAppContext){
    console.log("zoomAppContext: " + zoomAppContext);
    var dec = decrypt(zoomAppContext, process.env.ZoomAppsOAuthClientSecret)
    console.log("dec: " + JSON.stringify(dec))
    var uid = dec["uid"]
    console.log("uid: " + uid)
  }
  ...
  next()
})

公開前のゲスト利用について
ゲスト利用（Guest Mode）を有効にすることでアカウント外ユーザ（別テナントのユーザ）での利用も可能ですが、Marketplaceでの公開申請後、承認されている必要があります。
開発中など公開前で確認されたい場合は、各ゲスト接続されている側で明示する必要があります。
詳しくはこちらを参照ください。https://marketplace.zoom.us/docs/zoom-apps/guides/guest-mode/

■ サンプル・ドキュメント類について

今回のサンプル：
ZoomApps Sample: https://github.com/ysawamura-zoom/Workshop/tree/main/ZoomApps

ドキュメント類 (オフィシャル・ドキュメント)：
Introduction to Zoom Apps:　https://marketplace.zoom.us/docs/zoom-apps/introduction/
Developing an App: https://marketplace.zoom.us/docs/zoom-apps/create-zoom-app/
ZoomApps SDK Reference: https://marketplace.zoom.us/docs/zoom-apps/js-sdk/reference/
Guest Mode: https://marketplace.zoom.us/docs/zoom-apps/guides/guest-mode/
Testing Zoom Apps: https://marketplace.zoom.us/docs/zoom-apps/guides/testing-zoom-apps/
Publishing an app: https://marketplace.zoom.us/docs/zoom-apps/publishing-an-app/publishing-an-app/