Salesforce Mobile Studio：開発者向けMobilePush API連携ガイド

Salesforce 開発者の視点から、Salesforce Marketing Cloud Engagement の強力なツールである Mobile Studio (モバイルスタジオ)、特に MobilePush (モバイルプッシュ) の API 連携に焦点を当てて、その技術的な側面を深掘りします。

背景と応用シーン

現代の顧客エンゲージメントにおいて、モバイルデバイスは中心的な役割を果たしています。顧客はリアルタイムでパーソナライズされた情報を期待しており、プッシュ通知は企業が顧客と直接的かつ即時的にコミュニケーションをとるための最も効果的なチャネルの一つです。Salesforce Marketing Cloud Engagement (旧称: Marketing Cloud) が提供する Mobile Studio は、MobilePush (プッシュ通知)、MobileConnect (SMS/MMSメッセージング)、そして GroupConnect (LINEなどのメッセージングアプリ連携) を包含する、包括的なモバイルマーケティングソリューションです。

開発者にとって Mobile Studio が重要となるのは、単にマーケティングキャンペーンを一斉配信するだけでなく、外部システムやアプリケーションのイベントをトリガーとして、動的かつトランザクショナルなメッセージを送信するシナリオです。具体的な応用シーンとしては、以下のようなものが挙げられます。

トランザクション通知

Eコマースサイトでの注文確定、商品発送、配達完了など、顧客のアクションに応じて即座にプッシュ通知を送信します。これにより、顧客は自身の注文状況をリアルタイムで把握でき、安心感と満足度が向上します。

行動トリガー型メッセージ

ユーザーがモバイルアプリ内でお気に入り商品を登録した、カートに商品を入れたが決済しなかった（カゴ落ち）、あるいは特定のコンテンツを閲覧したといった行動を検知し、それに関連するパーソナライズされたメッセージを自動送信します。これは、REST API (Representational State Transfer Application Programming Interface) を通じて実現されます。

Salesforce CRM との連携

Salesforce Sales Cloud や Service Cloud 上で、特定の条件（例：商談がクローズした、ケースが解決した）を満たした際に、Apex トリガーやフローから Marketing Cloud の API を呼び出し、担当者や顧客にプッシュ通知を送信します。これにより、ビジネスプロセスと顧客コミュニケーションをシームレスに連携させることが可能になります。

原理説明

MobilePush の API 連携を理解するためには、いくつかの重要な概念と技術フローを把握する必要があります。開発者の観点から、その仕組みを解説します。

MobilePush SDK

MobilePush の機能をネイティブの iOS や Android アプリに組み込むためのライブラリが MobilePush SDK (Software Development Kit) です。この SDK の主な役割は以下の通りです。

デバイス登録: アプリがインストールされると、SDK は APNs (Apple Push Notification service) や FCM (Firebase Cloud Messaging) からデバイストークンを取得し、Marketing Cloud に安全に送信します。
Contact Key の紐付け: 最も重要な概念の一つが Contact Key (連絡先キー) です。これは、Marketing Cloud 内のすべてのチャネルで顧客を一意に識別するためのIDです。通常、Salesforce CRM の Contact ID や、自社システムのユーザーIDなどを設定します。SDK は取得したデバイストークンをこの Contact Key に紐付けます。これにより、「どの顧客」が「どのデバイス」を使用しているかを管理します。
エンゲージメント追跡: プッシュ通知の開封や、アプリ内での行動を追跡し、そのデータを Marketing Cloud に送り返します。これにより、マーケティング担当者はキャンペーンの効果を測定できます。

Transactional Messaging REST API

リアルタイムで個別のメッセージを送信するために使用するのが、Marketing Cloud の Transactional Messaging REST API です。この API を利用することで、外部システムから特定のメッセージ定義を呼び出し、特定の Contact Key を持つデバイスに対してメッセージを送信できます。

API 連携の一般的なフローは以下のようになります。

認証: Marketing Cloud の [セットアップ] > [アプリケーション] > [インストール済みパッケージ] で API 連携用のコンポーネントを作成します。ここで発行されるクライアントID、クライアントシークレット、および認証ベース URI を使用して、OAuth 2.0 のアクセストークンを取得します。このトークンは、後続の API リクエストの認証ヘッダーに含める必要があります。
メッセージ定義の作成: Marketing Cloud の MobilePush 上で、送信するメッセージのテンプレート（タイトル、本文、画像、遷移先など）を「APIトリガー」として事前に作成しておきます。このメッセージ定義には一意の `message key` が割り当てられます。
API リクエスト: 外部システム（例: 自社のバックエンドサーバー）は、何らかのイベントが発生した際に、ステップ1で取得したアクセストークンを使い、Marketing Cloud のメッセージ送信エンドポイントに対して POST リクエストを送信します。リクエストボディには、ステップ2で作成したメッセージの `message key` と、送信対象となるユーザーの `Contact Key` を含めます。
メッセージ配信: API リクエストを受け取った Marketing Cloud は、指定された `Contact Key` に紐づくデバイストークンを特定し、APNs または FCM を介して対象デバイスにプッシュ通知を配信します。

示例代码

ここでは、特定の `message key` を使用して、特定の `Contact Key` を持つ購読者にプッシュ通知を送信する Transactional Messaging API のリクエスト例を示します。このコードは Salesforce Developer の公式ドキュメントに基づいています。

まず、Marketing Cloud で `order_confirmation_push` という外部キー（`message key`）を持つプッシュ通知メッセージを事前に作成しておく必要があります。

APIエンドポイント:

POST `/messaging/v1/messageDefinitionSends/key:{messageKey}/send`

リクエストの例 (JSON):

{
  "To": {
    "Address": "device_token_goes_here", // この値は通常APIでは使用されませんが、MobilePushではContact Keyで解決されるため、ダミー値でも可
    "SubscriberKey": "user_12345", // これが最も重要。対象となるユーザーのContact Key
    "ContactAttributes": {
      "SubscriberAttributes": {
        "FirstName": "Taro", // メッセージ内でパーソナライズに使用する属性
        "OrderNumber": "ORD-00987", // 同上
        "ShippingDate": "2023-10-27" // 同上
      }
    }
  },
  "Options": {
    "RequestType": "ASYNC" // 非同期処理を推奨。大量送信時にAPIの応答性を保つ
  }
}

コードの解説

`To.SubscriberKey`: メッセージの送信先となる顧客の `Contact Key` を指定します。MobilePush SDK によってデバイスと正しく紐付けられている必要があります。これがメッセージ配信の核となるキーです。
`To.ContactAttributes.SubscriberAttributes`: これは動的なコンテンツをメッセージに挿入するためのデータです。Marketing Cloud のメッセージ定義側で、`%%FirstName%%` や `%%OrderNumber%%` のようなパーソナライゼーション文字列（AMPscript も可）を使用している場合、ここで渡された値がメッセージに差し込まれます。「Taro様、ご注文 (ORD-00987) の発送が完了しました。」といった、顧客一人ひとりに合わせたメッセージを作成できます。
`messageKey`: URL パスに含まれるこの部分は、事前に Marketing Cloud で作成したメッセージ定義の外部キーに置き換えます。例えば、`.../key:order_confirmation_push/send` のようになります。
`Options.RequestType`: `ASYNC` (非同期) を指定すると、Marketing Cloud はリクエストを受け付けた後すぐに `202 Accepted` レスポンスを返し、実際のメッセージ送信はバックグラウンドで処理します。これにより、送信側のシステムは長時間レスポンスを待つ必要がなくなります。

注意事项

権限 (Permissions)

API 連携を行うには、Marketing Cloud で作成したインストール済みパッケージに適切なスコープを付与する必要があります。MobilePush の送信には、最低でも以下の権限が必要です。

`PUSH: Read, Write`
`Journeys: Read`

権限が不足している場合、API は `403 Forbidden` エラーを返します。

API 制限 (API Limits)

Salesforce Marketing Cloud の API には、プラットフォームの安定性を維持するためのレート制限が存在します。短時間に大量のリクエストを送信すると、`429 Too Many Requests` エラーが返される可能性があります。高スループットが要求されるシステムを設計する際は、リクエストをバッチ処理する、リトライ処理にエクスポネンシャルバックオフを実装するなどの対策を検討する必要があります。

エラー処理 (Error Handling)

API 連携を実装する際は、堅牢なエラー処理が不可欠です。API から返される HTTP ステータスコードを正しく解釈し、ログに記録することが重要です。

`202 Accepted`: リクエストは正常に受け付けられました（非同期の場合）。
`400 Bad Request`: リクエストボディの形式が不正です。JSON の構文エラーや必須フィールドの欠落が考えられます。
`401 Unauthorized`: アクセストークンが無効、または有効期限が切れています。トークンの再取得処理が必要です。
`404 Not Found`: 指定された `message key` が存在しません。
`500 Internal Server Error`: Marketing Cloud 側で予期せぬエラーが発生しました。レスポンスボディに含まれる `requestId` を控えて、Salesforce サポートに問い合わせる必要があります。

まとめとベストプラクティス

Salesforce Mobile Studio、特に MobilePush の API 連携は、開発者が顧客エンゲージメントを次のレベルに引き上げるための強力な手段です。リアルタイムのデータと連携することで、単なる一斉配信ではない、真に価値のあるパーソナライズされたコミュニケーションを実現できます。

最後に、開発者としてのベストプラクティスをいくつか挙げます。

一貫性のある Contact Key 戦略: 組織全体で統一された、安定的で一意な `Contact Key` を使用してください。これがデータ統合と顧客識別の基盤となります。
認証情報の安全な管理: クライアントIDやシークレットなどの認証情報を、コードにハードコーディングせず、安全な場所に保管してください（例：環境変数、シークレット管理ツール）。
パーソナライゼーションの活用: `ContactAttributes` を最大限に活用し、顧客データに基づいた動的なメッセージを作成しましょう。静的なメッセージよりもはるかに高いエンゲージメントが期待できます。
非同期処理の採用: 大量送信の可能性がある場合は、`RequestType: ASYNC` を積極的に利用して、システムのパフォーマンスと安定性を確保してください。
マーケティングチームとの連携: 開発者は技術的な実装を、マーケティングチームはコミュニケーション戦略とコンテンツ作成を担当します。両者が密に連携し、どのようなデータを API 経由で渡す必要があるか、どのようなシナリオでメッセージをトリガーするかを共同で設計することが、プロジェクト成功の鍵となります。

これらの原理と実践方法を理解することで、開発者は Mobile Studio のポテンシャルを最大限に引き出し、優れたモバイル体験を顧客に提供することができるでしょう。

にゃんこのSalesforce日記

このブログを検索