> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SaaS アプリ開発者ガイド

> DingTalk（YiDA）Cool SaaS Factory を利用した SaaS アプリ構築のエンドツーエンドガイド。ローコード開発の前提条件、SaaS 開発ワークベンチへのアクセス、aPaaS プラットフォーム機能、メインアプリとクールアプリの設計、リリース・公開までの手順を解説します。

📎627 DingTalk (YiDA) Cool SaaS Factory アプリ開発者ガイド アウトライン.pdf

## 1 ローコード SaaS アプリ開発のエンドツーエンドプロセス

パートナーシッププロセスガイド - Open Platform を参照してください。

### 1.1 前提条件

<Steps>
  <Step title="ステップ 1">
    DingTalk 製品サービスプロバイダーの資格を申請します。
  </Step>

  <Step title="ステップ 2">
    [DingTalk Open Platform ISV ヘルプセンター](https://alidocs.dingtalk.com/i/p/KrwmPQ5g4OEAG79n/docs/3KLw95QMzkb8gGOpYEk78AjrymPeEN2q?dontjump=true) の全内容を確認します。
  </Step>

  <Step title="ステップ 3">
    SaaS アプリはクールアプリの形態を取る必要があります。アプリの変換方法については、[DingTalk 向けローコードクールアプリ設計ガイド](https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/7Y36k14mK9AV35vAPyg185NqapjblR2D) を参照してください。
  </Step>
</Steps>

### 1.2 SaaS 開発ワークベンチへのアクセス方法

組織が 製品ソリューションプロバイダー 認証を保有している場合、YiDA にログインすると、上部メニューに「SaaS 開発ワークベンチに入る」のエントリが表示され、直接アクセスできます。

SaaS アプリワークベンチでは、SaaS アプリを作成できます。

### 1.3 対応する aPaaS プラットフォーム機能

DingTalk SaaS Factory 開発ワークベンチは、既存の YiDA のインタラクションモデルをそのまま踏襲しています。本リリースでは以下のコア機能を提供します。

* プラットフォーム機能：

注：カスタムコネクタ、データ準備、DataV ダッシュボード、カスタムコンポーネントなどの拡張機能はまだ対応していません。今後のイテレーションで順次追加される予定です。

## 2 メインアプリの設計

> 前提条件が完了したら、SaaS アプリの構築を開始できます。他の YiDA 組織で完全なソリューションを保有しており、それを直接 SaaS モードに切り替えたい場合は、YiDA プロダクト・エンジニアリングチームに連絡し、SaaS 環境への移行を申請してください。

1. SaaS 開発ワークベンチと現在プラットフォームが提供している機能を使用し、業務要件に合わせてアプリを設計します。例：

上記機能の開発フローは、YiDA の社内アプリ開発と同じです。問題が発生した場合は YiDA チームまでお問い合わせください。

2. SaaS 製品に関連するベースライン業務データがあり、サブスクライブ後にサンプルデータをサブスクライバーに表示させたい場合は、この「ベースラインデータ」を入力し、「ベースライン業務データ」という単一のフォルダーに格納して管理してください（下記の例を参照）。

## 3 クールアプリの設計

SaaS 開発ワークベンチでは、アプリ層の「カード管理／統合と自動化フロー」において、クールアプリのカードスタイル、およびカードの送信・更新ロジックを設定できます。詳細な設計ガイダンスについては、以下のドキュメントを参照してください。

## 4 アプリのリリース

<Steps>
  <Step title="ステップ 1">
    メインアプリとクールアプリの両方の構築が完了したら、「リリース・公開」画面に移動し、SaaS アプリの機能テスト用に新しいバージョンを作成します。テストに合格した後、アプリの公開申請を送信します。
  </Step>

  <Step title="「バージョン作成」をクリックし、バージョン番号やリリースノートなどの SaaS アプリのバージョン情報を入力します。" />
</Steps>

### 4.1 アプリバージョン管理

* アプリの機能に変更があった場合は、新しいバージョンを作成できます。新しいバージョンはデフォルトで「未公開」状態です。「公開」をクリックしてバージョンをリリースします。

### 4.2 アプリ公開申請 — サードパーティアプリのリンク

#### ステップ 1：サードパーティアプリをリンク

| **SaaS 開発ワークベンチ**                                                                                                     | **DingTalk Open Platform > サードパーティ社内アプリ**                                                      |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 1. 少なくとも 1 つのアプリバージョンを作成後、「DingTalk App Center への公開」で公開申請を送信します。<br />2. Open Platform で登録したサードパーティアプリを選択し、ここでリンクします。 | 1. DingTalk Open Platform のサードパーティ社内アプリで H5 マイクロアプリを作成し、アプリの基本情報を入力します。<br />2. アプリ認証情報を生成します。 |

#### ステップ 2：SaaS アプリ開発情報の入力

SaaS アプリの URL をコピーして、アプリ情報を設定します。

| **SaaS 開発ワークベンチ**                                           | **DingTalk Open Platform > サードパーティ社内アプリ**                                           |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 1. ステップ 1 完了後、「コピー」をクリックし、右図のように Open Platform にリンクを貼り付けます。 | 1. DingTalk Open Platform のサードパーティ社内アプリで、登録済みのサードパーティアプリを選択し、「開発管理」をクリックして以下を入力します。 |

#### ステップ 3：SaaS アプリ設定項目の確認

##### (1) アプリ開発情報の確認

1. DingTalk Open Platform のサードパーティ社内アプリで、登録済みのサードパーティアプリを選択し、すべての機能設定項目が完了していることを確認します。未完了の項目があれば入力を完了させます。

##### (2) 権限管理

SaaS 製品のデータを保護するため、アプリはアクティベーション時にユーザーと認可スコープを確認する必要があります。ISV は必要な権限スコープを自身で設定する必要があります。

1. 「権限管理」メニューを選択します。標準的な SaaS 製品は以下の権限を選択し、「一括申請」をクリックする必要があります。

| **権限カテゴリ** | **権限スコープ**                                                                            |
| ---------- | ------------------------------------------------------------------------------------- |
| カード        | インタラクティブカードインスタンスへの書き込みアクセス                                                           |
| 個人権限       | 連絡先プロフィールへの読み取りアクセス                                                                   |
| 連絡先管理      | 連絡先部門情報への読み取りアクセス<br />連絡先部門ユーザーへの読み取りアクセス<br />業界連絡先情報のクエリアクセス<br />ユーザー情報への読み取りアクセス |
| タスク        | タスクアプリ内のタスクアイテムへの書き込みアクセス<br />タスクアプリ内のタスクアイテムへの読み取りアクセス                              |
| アプリ認可      | ISV 専用 API を呼び出すために必要な権限                                                              |
| 認証         | 社内マイクロアプリバックエンドのサイレントログイン API へのアクセス                                                  |
| シーングループ    | チャット関連 API への管理アクセス<br />チャット関連 API への読み取りアクセス                                        |
| YiDA       | **すべて選択**                                                                             |
| ボット        | 社内ボットが社内でメッセージを送信する権限                                                                 |
| ストレージ      | 組織ストレージスペースへの読み取りアクセス<br />組織ストレージファイルへの書き込みアクセス<br />組織ストレージファイルへの読み取りアクセス           |

（図 1：権限設定画面）

（図 2：権限を付与通知画面）

2. SaaS 製品が「統合と自動化 > コネクタノード」の「DingTalk 公式」コネクタを使用する場合は、YiDA チームに連絡し、選択する必要があるファーストパーティコネクタの権限を確認してください。

コネクタと権限のマッピング（一部）：

| **コネクタ** | **権限カテゴリ** | **権限スコープ**               |
| -------- | ---------- | ------------------------ |
| スマート会議室  | スマート会議室    | ビデオ会議アプリ内の会議への書き込みアクセス   |
| プロジェクト管理 | プロジェクト管理   | プロジェクトアプリ内のタスクへの書き込みアクセス |

#### ステップ 4：セキュリティセルフチェックのスキップを自主申請

1. セルフチェックをスキップするには、以下のように「イベントとコールバック」を設定します。

**ステップ 1**：暗号化 Aes\_key には、以下の **decrypt** メソッドで YiDA の **systemToken** を暗号化した結果を設定します。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
private static final char[] HEX_ARRAY = "0123456789abcdef".toCharArray();

public static String bytesToHex(byte[] bytes) {
        char[] hexChars = new char[bytes.length * 2];
        for (int i = 0; i < bytes.length; i++) {
            int v = bytes[i] & 0xFF;
            hexChars[i * 2] = HEX_ARRAY[v >>> 4];
            hexChars[i * 2 + 1] = HEX_ARRAY[v & 0x0F];
        }
        return new String(hexChars);
    }

private static String decrypt(String input) throws NoSuchAlgorithmException {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
        // ハッシュを 43 文字の暗号化文字列に変換
        return bytesToHex(hash).substring(0, 43);
}
```

YiDA の systemToken は、YiDA アプリの「設定 > デプロイと運用」から取得します。

**ステップ 2**：署名 Token は、上記の YiDA systemToken と同じです。

**ステップ 3**：コールバックリクエスト URL（[https://www.yidaapps.com/saasAppCallback/\\\{appKey}）。appKey](https://www.yidaapps.com/saasAppCallback/\\\{appKey}）。appKey) は YiDA アプリコード（例：「APP\_XXX」）です。

2. アプリセルフチェックの「セキュリティレビュー」内容を完了させます。セキュリティ受け入れ評価については、📎YiDA Cool SaaS セキュリティ受け入れガイド - ISV.pdf を参照してください。

### 4.3 Trial 組織管理

Trial 組織管理は、公開済み・未公開状態のメインアプリとクールアプリを ISV がセルフテストする際に使用します。セルフテスト合格後、DingTalk App Center およびクールアプリマーケットプレイスへのアプリ公開申請を送信します。

<Steps>
  <Step title="ステップ 1">
    SaaS アプリのバージョンを選択し、「Trial 組織管理」をクリックして Trial 組織を選択します。Trial 組織が存在しない場合は、「作成」をクリックして Open Platform にアクセスし作成します。
  </Step>

  <Step title="ステップ 2">
    Trial 組織を作成後、テストしたいアプリバージョンをリンクして権限付与します。権限付与が成功すると、その Trial 組織のワークベンチ > 未グループ分けにアプリが表示されます。
  </Step>
</Steps>

#### 4.3.1 メインアプリの Trial テスト

<Steps>
  <Step title="ステップ 1">
    ワークベンチからアプリにアクセスします。Trial テスト担当者が「連絡先管理者」または「アプリスーパー管理者」でない場合は、組織管理者またはアプリ管理者に依頼してアプリバックエンドへのアクセス権を付与してもらいます。
  </Step>

  <Step title="アプリ管理バックエンドへのアクセス権を取得したら、サブスクライブした SaaS アプリのバックエンド設定を確認します。特定の機能は変更可能です。" />
</Steps>

**以下の機能はすべて変更可能です：**

> 一般ロジック：変更を行った後、ISV が新しいバージョンをリリースした場合、対象機能については顧客のローカル設定が優先されます。メインアプリの変更は子アプリに同期されません。変更を行わなかった場合、メインアプリの増分リソース変更は子アプリに同期されます。
>
> 承認フロー変更ロジック：
>
> 1. 子アプリが V0 をサブスクライブしており、メインアプリに未公開の V1 がある場合、V1 は子アプリのバージョン履歴に表示されません。
> 2. 子アプリがカスタマイズなしで V0 をサブスクライブしており、メインアプリが後に V1 にアップグレードした場合、子アプリは引き続きサブスクライブ済みの V0 を表示・実行します。
> 3. 子アプリが V0 をサブスクライブしてカスタマイズを行った場合、V0 の内部履歴バージョンと V1 のドラフトが作成されます。子アプリが新バージョンをサブスクライブした後は、現在のプロセスはメインアプリのアップグレードに追従しなくなります。
> 4. 上記のバージョンスコープには、バージョン内のすべての業務ルールや式が含まれます。

3. デフォルトで、メインアプリの「ベースライン業務データ」フォームのデータが子アプリに引き継がれ、ベースラインデータがそのまま動作します。変更にも対応しています。

#### 4.3.2 クールアプリの Trial テスト

<Steps>
  <Step title="ステップ 1">
    メインアプリのテストが合格した後、クールアプリをテストします。まず、クールアプリの情報を送信します。「DingTalk クールアプリマーケットプレイスへの公開 > 公開申請の送信」をクリックし、基本情報、アクセスエントリ（最大 3 つ）、公開方法、ボット情報を含むクールアプリの公開情報を入力します。
  </Step>

  <Step title="情報入力後、「保存して公開」をクリックし、coolappcode を生成します。" />

  <Step title="このクールアプリの coolappcode をコピーし、現在の Trial 組織に内部グループを作成して、下記のようにモバイルにインストールしてテストします。" />
</Steps>

## 5 アプリ運用

### 5.1 バージョンアップグレード

ISV が構築した SaaS アプリがアプリマーケットプレイスに公開され顧客がサブスクライブした後、ISV は機能をイテレーションし、「YiDA SaaS 開発ワークベンチ > アプリ設定 > リモート運用」で特定の組織に対して個別または一括でバージョンアップグレードを展開できます。

機能に関する注意：

1. デフォルトでは、アップグレード対象は現在公開中のバージョン以降にリリースされた最新のイテレーションです。
2. 複数の有料組織にまたがる一括バージョンアップグレードに対応しています。

> リモート運用機能は近日公開予定です。

### 5.2 アプリアクティベーション権限付与ランディングページ

YiDA SaaS アプリが DingTalk Open Platform および App Center に公開された後、権限付与ランディングページをカスタマイズできます。👉詳細はこちら

設定に関する注意：

* PC 版とモバイル版の権限付与ランディングページを別々にアップロードします（チャンネルごとに 1 枚のみサポート）。

* アップロード後、「Trial アクセス URL」をコピーし、パートナー自主運営プラットフォーム > サードパーティ社内アプリ > 製品公開管理 > アプリ詳細 > 管理 > 「アプリ内権限付与設定」に移動します。統合が完了しセルフ受け入れが合格した後（👉 受け入れプロセスの詳細はこちら）、SaaS アプリを DingTalk 検索など、DingTalk のより多くのオンラインチャンネルで展開できるようになります。

| モバイル表示 | PC 表示 |
| ------ | ----- |

## 6 FAQ

<AccordionGroup>
  <Accordion id="q1" title="Q1: サブスクライブした SaaS アプリのフォームフィールドを変更するには？">
    A: フォームなどの機能の変更にはすでに対応しています。
  </Accordion>

  <Accordion id="q2" title="Q2: 公開済みのフォームからコンポーネントを削除できますか？">
    A: 公開済みの標準フォームや作業フロー フォーム（サブフォームを含む）からコンポーネントを削除することはできません。
  </Accordion>

  <Accordion id="q3" title="Q3: 公開済みのカスタムページに固定 CorpId を含めることはできますか？">
    A: カスタムリンクに固定 CorpId を含めることはできません。
  </Accordion>

  <Accordion id="q4" title="Q4: クールアプリのインストールが失敗する場合はどうすればよいですか？">
    A: メインアプリの組織以外の組織で新しい内部グループを作成し、そこにインストールしてクールアプリをテストしてください。
  </Accordion>

  <Accordion id="q5" title="Q5: カスタムページからフォームページへリダイレクトする際に、現在のグループ ID を渡すには？">
    「クールアプリ FAQ と代表的なシナリオ設計ガイド」を参照してください。
  </Accordion>

  <Accordion id="q6" title="Q6: SaaS アプリページのメニューとナビゲーションバーを非表示にするには？">
    A: YiDA ページが他システムに埋め込まれる場合、上部ナビゲーションバーと左側のページ機能ナビゲーションバーの両方を非表示にできます。埋め込みページ URL に ?isRenderNav=false を付加してください。
  </Accordion>
</AccordionGroup>