このパッケージを使用すると、Zendesk App Framework (ZAF) と統合された React ベースのアプリケーションをブートストラップでき、Zendesk Sell 用のアプリの開発をすぐに開始できるようになります。
注: このドキュメントは、Zendesk 開発者ガイドに基づいています。これらには、Zendesk Sell と統合されたアプリの作成に関して、選択された、できれば最も必要な情報のみが含まれています。何か問題がある場合、またはここに十分な情報がない場合は、実際のドキュメントを参照してください。
Zendesk 製品にアプリを正常にインストールするには、次のフォルダー構造とファイルがアプリに含まれている必要があります。
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
以下に、必要なファイルの簡単な説明を示します。
Sell アプリの HubSpot マニフェストの例:
{
"name" : " Hubspot " ,
"author" : {
"name" : " Zendesk " ,
"email" : " [email protected] " ,
"url" : " https://www.zendesk.com "
},
"defaultLocale" : " en " ,
"private" : false ,
"singleInstall" : true ,
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
}
}
},
"version" : " 2.0.3 " ,
"frameworkVersion" : " 2.0 " ,
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
],
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}
}各製品インターフェイス内でアプリを表示する場所を、manifest.json のlocationプロパティで宣言する必要があります。これらの場所は、製品内で iframe を表示できる場所です。 1 つまたは複数の Zendesk 製品で 1 つまたは複数の場所を指定できます。デフォルトでは、アプリはZendesk Sellの右側のパネルのすべてのオブジェクトカード（リード、取引先責任者、取引）で利用可能になります。
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
},
"deal_card" : {
"url" : " assets/index.html "
}
}
}利用可能な場所については、「Sell Apps API」を参照してください。アプリの場所の設定の詳細については、開発者ガイドの「アプリの場所の設定」セクションを参照してください。
アプリが AJAX リクエストを行う場合、リクエストの設定はブラウザー コンソールで確認できます。一部の設定には、API キーやトークンなどの機密情報が含まれる場合があります。この動作を防ぐために推奨される方法は、 OAuth Authentication使用することです。もう 1 つのオプションは、 Secure Settingsを使用することです。最適なオプションをお選びください。
OAuth2 を使用して、外部サービスへのすべての API リクエストを認証できます。 OAuth は、ユーザー名やパスワードなどの機密情報をリクエストとともに送信する必要がなく、アプリケーションがアカウント データにアクセスするための安全な方法を提供します。 OAuth 認証を使用するには、アプリケーションをサードパーティ サービスに登録して、アプリケーションの OAuth 資格情報を生成する必要があります。 OAuth 認証フローを実装するには、アプリケーションにいくつかの機能を追加する必要もあります。
アプリを登録すると、アプリ名、説明、入力する必要があるその他のアプリ情報など、新しいアプリの設定を示す画面が表示されます。さらに、認証設定も表示されます。クライアント ID、クライアント シークレット、リダイレクト URL、およびアプリで使用されるスコープなどのアプリ。これらのアイテムは、アプリとサードパーティのサービスの間で OAuth 接続を開始するときに必要になります。
Client ID - この ID はアプリに固有であり、OAuth の開始に使用されます。Client secret - OAuth 認証の確立と更新に使用されます。Redirect URL - アプリへのアクセスを許可した後、ユーザーはこの場所にリダイレクトされます。次の URL のいずれかを使用します。Scope - オプションのセキュリティ対策。スコープは、アプリがどのデータにアクセスする権限を持っているかを決定します。OAuth URL - ユーザーがアプリに接続するにはこの URL が必要です。 URL は、アプリのクライアント資格情報、リダイレクト URL、およびスコープ構成に基づいて構築されます。次のセクションで説明するように、アプリケーションでClient IDとClient secretを使用します。
アプリを登録したら、 manifest.jsonファイルで OAuth 設定を定義する必要があります。 client_idとclient_secret自分のものに更新します。
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}また、タイプ「oauth」のパラメータをパラメータ リストに追加する必要があります。
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]詳細については、ドキュメントを参照してください
アプリ コードで、プレースホルダー{{setting.access_token}}とsecure: trueプロパティを使用して、OAuth リクエストを作成します。
var settings = {
url : 'https://www.example.com/api/user' ,
headers : { "Authorization" : "Bearer {{setting.access_token}}" } ,
secure : true ,
type : 'GET'
} ;
var client = ZAFClient . init ( ) ;
client . request ( settings ) . then ( ... ) ;これは JSON のみの API です。 PUT リクエストおよび POST リクエストにはContent-Type: application/jsonヘッダーを指定する必要があります。すべてのリクエストにAccept: application/jsonヘッダーを設定する必要があります。
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; 安全な設定は、AJAX リクエストを行うときにエージェントが設定にアクセスできないようにするもう 1 つの方法です。設定値は、送信リクエストのサーバー側のプロキシ層にのみ挿入されます。これらを設定するには、「安全な設定を使用する」を参照してください。
アプリの外観には任意のカスタム CSS またはフロントエンド フレームワークを使用できますが、Zendesk では Zendesk Garden の使用を推奨しています。 Zendesk Garden は、すべての Zendesk 製品間でのスタイルとコンポーネントの共通のベースラインとなるように設計されています。アプリを Zendesk のルック アンド フィールに一致させるために、アプリでは Zendesk Garden がデフォルトとして使用されます。
例：
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}Zendesk Garden の CSS クラスと React コンポーネントの詳細については、garden.zendesk.com を参照してください。
ZAF クライアントを使用すると、iframe 内のアプリがホストの Zendesk 製品と通信できるようになります。アプリでクライアントを使用して、イベントをリッスンし、アクションを呼び出し、各場所のプロパティにアクセスできます。 ZAF クライアント API ガイドを参照してください。
例：
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )@zendesk/sell-zaf-app-toolbox パッケージは、Zendesk Sell と統合された React アプリをより迅速かつ少ない労力で構築するのに役立つ便利なメソッド、フック、コンポーネントを多数提供します。彼らは内部で Zendesk の App Framework クライアントを使用しています。詳細については、リポジトリにアクセスしてください。
コマンドライン インターフェイスを使用して、テストするアプリが含まれるフォルダーに移動します。
必要に応じて依存関係をインストールします。
npm install次のコマンドでアプリを起動します。
npm startターミナルで新しいウィンドウを開き、サーバーを起動します。
npm run server
ブラウザで、表示するアプリを指定した製品ページ (取引/リード/連絡先カードなど) に移動し、URL に?zcli_apps=true追加します。例：
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
ブラウザのアドレス バーで、右側の盾アイコン (Chrome) または左側の鍵アイコン (Firefox) をクリックし、安全でないスクリプトのロード (Chrome) または保護の無効化 (Firefox) に同意します。
注: Safari には保護を無効にするオプションがありません。
lint を実行していくつかのエラーを自動的に修正するには、次のコマンドを実行します。
npm run lintコードをフォーマットするには:
npm run prettier縮小されたソースを含むパッケージをビルドします。
npm run buildこのコマンドはdist/tmpに新しい .zip ファイルを作成します。これで、アプリを Zendesk Sell にプライベート アプリとしてインストールする準備が整いました。
Integrationsセクションを見つけて、 Appsタブを選択します。Upload private appボタンをクリックします。dist/tmpからアップロードします。アプリで OAuth または安全な設定を使用している場合は、リモートでインストールした後もローカルでテストを続けることができます。
zcli.apps.config.jsonという名前のファイルを作成します。planとparamtersキーを変更することもできます)。 {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
}アプリのインストール ID を確認するには、Zendesk Sell インスタンスに管理者としてサインインし、同じブラウザで次のページを開き、 your_subdomain自分のものに置き換えます。
https://your_subdomain.zendesk.com/api/sell/apps/installations.json (本番環境)
インストールされているアプリを見つけて、 app_id値ではなく、そのid値をメモします。
