API 呼び出し

コネクテッドコンテンツを使用して、ユーザーに送信するメッセージに API を介して直接アクセス可能な情報を挿入します。Web サーバーから直接、またはパブリックにアクセス可能な API からコンテンツをプルできます。

コネクテッドコンテンツタグ

コネクテッドコンテンツ呼び出しを送信するには、{% connected_content %} タグを使用します。このタグでは、:save を使用して変数を割り当てたり宣言したりできます。これらの変数の内容には、メッセージの後の方で Liquid を使って参照できます。

たとえば、次のメッセージ本文は、http://numbersapi.com/random/trivia という URL にアクセスし、メッセージに楽しいトライビアを含めます。

1
2
{% connected_content http://numbersapi.com/random/trivia :save result %}
Hi there, here is fun some trivia for you!: {{result.text}}

変数の追加

また、コネクテッドコンテンツリクエストを作成するときに、URL 文字列に変数としてユーザープロファイル 属性を含めることもできます。

たとえば、ユーザーのメールの住所とID に基づいてコンテンツを返すウェブサービスがあるとします。アットマーク (@) などの特殊文字を含む属性を渡す場合は、URL で使用できない文字を URL フレンドリなエスケープバージョンで置き換えるために、Liquid フィルター url_param_escape を必ず使用してください (次のメールアドレス属性を参照)。

1
2
3
Hi, here are some articles that you might find interesting:

{% connected_content http://www.yourwebsite.com/articles?email={{${email_address} | url_param_escape}}&user_id={{${user_id}}} %}

接続コンテンツリクエストは、GET およびPOST リクエストのみをサポートします。

エラー処理

URL が使用できず、404 ページに達すると、Braze はその場所に空の文字列を表示します。URL がHTTP 500 または502 ページに達すると、URL は再試行ロジックで失敗します。

エンドポイントがJSON を返す場合は、connected の値がnull であるかどうかを確認して、条件付きでメッセージ を中止することで、そのことを検出できます。Braze では、ポート 80 (HTTP) と 443 (HTTPS) を介して通信する URL のみが許可されます。

パフォーマンス

Braze はメッセージを非常に高速で配信するため、サーバーが数千の同時接続を処理できるようにして、コンテンツをプルダウンするときにサーバーが過負荷状態にならないようにしてください。パブリック API を使用する場合は、API プロバイダーが使用するレート制限に違反しないように使用してください。Braze では、パフォーマンス上の理由からサーバーの応答時間が2 秒未満である必要があります。サーバーの応答時間が2 秒を超えると、その内容は挿入されません。

Braze は、各受信者に複数回、同じコネクテッドコンテンツ API 呼び出しを行うことができます。これは、状況によっては Braze がメッセージペイロードを表示するためにコネクテッドコンテンツ API 呼び出しを行う必要があり、メッセージペイロードは、検証、再試行ロジック、またはその他の内部目的のために、受信者ごとに複数回レンダリングされることがあるためです。システムは、各受信者につき複数回、同じコネクテッドコンテンツ API 呼び出しの処理を行わなければなりません。

知っておくべきこと

• Braze は API 呼び出しについて課金せず、指定のデータポイント割り当てにはカウントされません。
• コネクテッドコンテンツ応答には 1 MB の制限があります。
• コネクテッドコンテンツ呼び出しは、メッセージの送信時に行われます。ただし、アプリ内メッセージは、メッセージが表示されたときにこの呼び出しを行います。
• コネクテッドコンテンツ呼び出しはリダイレクトに従いません。

認証タイプ

基本認証の使用

URL に基本的な認証が必要な場合、Braze は API 呼び出しで使用するための基本的な認証情報を生成できます。既存の基本的な認証情報を管理したり、[設定] > [コネクテッドコンテンツ] から新しいものを追加したりできます。

新しい認証情報を追加するには、認証情報を追加します。認証情報に名前を付け、ユーザーの名前とパスワードを入力します。

次に、トークンの名前を参照することで、API 呼び出しでこの基本的な認証情報を使用できます。

1
Hi there, here is fun some trivia for you!: {% connected_content https://yourwebsite.com/random/trivia :basic_auth credential_name %}

トークン 認証の使用

Braze コネクテッドコンテンツを使用する場合、特定の API では、ユーザー名とパスワードの代わりにトークンが必要になることがあります。次の呼び出しに含まれているのは、メッセージを参照し、それをメッセージのモデルとして使用するためのコードスニペットです。

1
2
3
4
5
6
7
8
9
10
11
12
{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://your_API_link_here/
     :method post
     :headers {
       "X-App-Id": "YOUR-APP-ID",
       "X-App-Token": "YOUR-APP-TOKEN"
  }
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

オープン認証(OAuth)の使用

一部の API 設定では、アクセスする API エンドポイントの認証に使用できるアクセストークンを取得する必要があります。

アクセストークンを取得する

次の例は、アクセストークンを取得してローカル変数に保存し、後続の API 呼び出しの認証に使用できるようにする方法を示しています。パラメーター :cache_max_age を追加して、アクセストークンの有効期間を照合し、アウトバウンドコネクテッドコンテンツ呼び出しの回数を減らすことができます。詳細については、構成可能なキャッシュ を参照してください。

1
2
3
4
5
6
7
8
9
10
{% connected_content
     https://your_API_access_token_endpoint_here/
     :method post
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "Bearer YOUR-APP-TOKEN"
  }
     :cache_max_age 900
     :save token_response
%}

取得したアクセストークンを使用して API を承認する

これでトークンが保存されたので、これをダイナミックなコネクテッドコンテンツ呼び出しにテンプレート化して、リクエストを承認できます。

1
2
3
4
5
6
7
8
9
{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
  }
     :body key1=value1&key2=value2
     :save response
%}

コネクテッドコンテンツ IP の許可リスト

コネクテッドコンテンツを使用したメッセージが Braze から送信されると、Braze サーバーは、自動的に顧客またはサードパーティのサーバーにネットワークリクエストを行い、データをプルバックします。IP 許可リストを使用すると、コネクテッドコンテンツリクエストが実際に Braze から送信されていることを確認し、セキュリティレイヤーを追加することができます。

Braze は、次のIP 範囲から接続コンテンツリクエストを送信します。リストされている範囲は自動的に追加され、許可リストにオプトインされているすべての API キーにダイナミックに追加されます。

Braze には、すべてのサービスに使用される一連の予約済み IP があります。これらの ＩＰ はすべて一度にアクティブになるわけではありません。これは、Braze が別のデータセンターから送信したり、保守を行ったりするために、顧客に影響を与えないように設計されています。Braze は、コネクテッドコンテンツリクエストを作成するときに、以下の IP のいずれか 1 つ、サブセット、またはすべてを使用できます。

トラブルシューティング

コネクテッドコンテンツ呼び出しのトラブルシューティングには、Webhook.site を使用します。

1. コネクテッドコンテンツ呼び出しの URL を、サイトで生成された一意の URL に切り替えます。
2. キャンペーンまたはキャンバスステップをプレビューしてテストし、リクエストがこの Web サイトを介して処理されることを確認します。

このツールを使用して、リクエストヘッダー、リクエスト本文、および呼び出しで送信される他の情報に関する問題を診断できます。