ディレクティブの作成と配信

メッセージにディレクティブを記述し、テスト配信で値を確認してから保存します。

ディレクティブは、APIを呼び出す行とレスポンスを使う行に分かれます。

• パスとクエリ文字列には、{{ userId }}、{{ tags.* }} などのパーソナライズ変数を使えます。ドメインの部分には使えません。
• メールアドレスのように @・+・& が含まれる可能性のある値は、url_encode で囲んでください。囲まないと値が崩れて渡されることがあります。

{% connected_content https://api.example.com/coupon?uid={{ userId }} %}
{% connected_content https://api.example.com/member?email={{ email | url_encode }} :save member %}

ドメインに変数を入れると保存できません。

{% connected_content https://{{ tags.domain }}/coupon %}

POSTの例

:body の {{ userId }} の部分に受信者の値が入るため、userIdがabc123の受信者であれば uid=abc123 が送信されます。

{% connected_content https://api.example.com/recommend :method post :body uid={{ userId | url_encode }} :save rec %}
おすすめ商品：{{ rec.product_name }}

JSONで送る場合も、bodyは キー=値 の形式で書き、値を url_encode で囲んでください。FlareLaneがJSONに変換して送信するため、値に引用符などの特殊文字が含まれていても崩れません。オプションが多い場合は、行を分けて書くこともできます。

名前が Kim "Flare" Lane であっても、{"uid": "…", "name": "Kim \"Flare\" Lane"} として正しく送信されます。

{% connected_content https://api.example.com/recommend
     :method post
     :content_type application/json
     :body uid={{ userId | url_encode }}&name={{ name | url_encode }}
     :save rec %}

JSONを直接書くと、値に引用符が含まれる受信者ではbodyが崩れ、APIが400エラーを返して空欄で配信されます。

{% connected_content https://api.example.com/recommend
     :method post
     :content_type application/json
     :body {"name": "{{ name }}"}
     :save rec %}

• 利用準備のステップでコピーしておいた認証情報を、URLの後ろに付けます。
• 1つのディレクティブでBasicとTokenを一緒に使うことはできません。

レスポンスがJSONかプレーンテキストかは、APIの Content-Type レスポンスヘッダーで決まります。開発チームから受け取ったレスポンス例で確認してください。2つの形式は取り出し方が異なります。

:save で名前を付け、名前の後ろにドット（.）を付けてフィールドを取り出します。同じ値を複数の場所で使え、取り出す値を後から追加するのも簡単です。

{% connected_content https://api.example.com/points?uid={{ userId }} :save point %}
失効予定のポイントは{{ point.amount }}ポイントです。{{ point.expires_at }}までご利用いただけます。

値を入れたい位置にディレクティブを直接書いてください。以下は、公開されている天気サービスを使ってユーザーの都市の現在の気温を差し込む例です。

今日の{{ tags.city }}の気温は{% connected_content https://wttr.in/{{ tags.city }}?format=%t %}です。お出かけ前に服装をチェックしてください！

呼び出しが失敗すると、値の部分は空欄になります。次の3つのうち1つを選んで、あらかじめ書いておくことをおすすめします。

値があるときだけ表示したり配信しないようにしたりするには、条件文で呼び出しが失敗したかを確認します。確認方法は2つあります。

条件文でも名前ではなくフィールドで確認してください。名前だけを書くとメッセージが保存できません。

{% if point == blank %}{% abort_message %}{% endif %}

同じURLをもう一度呼び出すときは、APIを毎回呼び出さず、先に受け取ったレスポンスを一定時間再利用します。ほとんどの場合はデフォルトの動作のままで問題なく、変更が必要なときだけオプションを書いてください。

• 例: tags.city だけを含む天気の呼び出しは、同じ都市どうしでレスポンスを再利用するため、受信者が多くても都市の数だけ呼び出されます。
• 同時に処理される受信者が多いと、同じURLでも複数回呼び出されることがあります。キャッシュは呼び出し回数を減らすものであり、必ず1回だけ呼び出されることを保証するものではありません。

:cache_max_age で指定できる範囲は、上限のまとめをご確認ください。

• 配信前に、テスト配信で最終的なメッセージを確認することをおすすめします。
• テスト配信も実際の配信と同じです。
  • 自社のAPIが実際に呼び出されます。
  • ステップ5の自動検査も同じように適用されます。
  • 指定した電話番号・メールアドレスに紐づくユーザーがいない場合、{{ userId }} などのユーザー情報が空になることがあります。

• 即時配信、予約の保存、繰り返し配信の保存、ジャーニー自動化の保存、メールテンプレートの保存のタイミングでディレクティブが自動的に検査され、記述ルールに反している場合は保存・配信されません。
• 記述ルールは、保存が拒否されるケースの内容をご確認ください。