Adjustは、自社サーバーのエンドポイントにコールバックをリアルタイムで提供するシステムを提供します。コールバックにより、Adjustのデータをリアルタイムでご利用のサーバーやビジネス インテリジェンス システムと連携することができます。

Adjustのコールバックにより、アプリにリダイレクトされたりアプリ経由で受け渡されるそれぞれのクリック、インストール、リアトリビューション、イベント、不正防止ツールが有効になっているアカウントで拒否されたインストール、更新されたアトリビューション、アンインストール、リインストール、リアトリビューションインストール、そして広告費用の更新に関するデータがリアルタイムに提供されます。adjustの利用者としてこのデータを活用し、どのような場所にもデータを送信するようAdjustに要求することができます。

このガイドでは、お客様のニーズと技術環境に適合する方法で、Adjustのコールバック ソリューションを実装する方法について説明します。広範なデータを取り出してカスタム分析を行ったり、コールバックを実装してアプリ内のデータを提供するなど、Adjustのコールバックは様々な方法で活用されています。

1用語解説

  • コールバック または ポストバック 特定のイベントの発生時に、Adjustのサーバーがご利用のサーバーに対して実行するデータ送信。
  • コールバックURL / ポストバックURL データの送信先となるサーバーを指すURL
  • プレースホルダ 特定の場所にAdjustサーバーが特定のデータを付与するための命令
  • パラメータ URLに追加される値
  • エンドポイント サーバー上の特定の場所
  • エンコード URLに含まれる特殊な文字を違う文字に置き換える処理
  • GET 標準的な種類のネットワーク要求

2Adjustダッシュボードへのコールバックの追加

ダッシュボードのイベント画面でコールバックを追加できます。各イベントの行にカーソルを合わせると「コールバックの追加」または「編集」ボタンが表示されます。このボタンをクリックして、コールバックの追加画面を開きます。

エンドポイントのURLと、利用可能なプレースホルダを使用した目的のパラメータと一緒に追加します。例えば、インストールごとにhttp://myserver.com/register/にコールバックを行い、それぞれのインストールのIDFA、タイムスタンプ、トラッカー名をパラメータとして設定したい場合は、以下の文字列を追加するとよいでしょう。

http://myserver.com/register/?idfa={idfa}&timestamp={created_at}&source={tracker_name}

中かっこ（{ }）内の文字がプレースホルダで、送信前にadjustサーバーによってに置き換えられます。プレースホルダを使用して受け取ることのできるデータについては、以下のプレースホルダのセクションで説明します。

もちろんプレースホルダを使用して、単純なGETパラメータ以外の構文を次のように構築することもできます。

http://myserver.com/register/{tracker_name}/{idfa}/?data={created_at}

ただし、カスタムSDKのパラメータは必ずGET構文を使用して構築されます。POSTリクエストはクライアント コールバックでは現在サポートされていません。

異なるURLをスペースで区切ることで、複数のコールバックを追加できます。

2.1更新されたアトリビューションやリアトリビューションのコールバック使用

更新されたアトリビューションやリアトリビューションにおけるコールバックはユーザーのアトリビューションデータが更新されている場合に限り、インストール、もしくはリアトリビューションのコールバックの後に送信されます。

アトリビューションとリアトリビューションを定義した後でも、Adjustはしばしばセルフ・アトリビューションのネットワークからアトリビューション情報を受信することもあります。ユーザーのアトリビューションデータが変更されている、このように稀な現象において、Adjustではそのユーザーのアトリビューション情報はAdjustのダッシュボードにて更新を行うようにしています。この場合、Adjustからは更新されたアトリビューション情報を「更新されたアトリビューション」のイベントとしてAdjustのダッシュボード内でコールバックを送信します。

更新されたアトリビューション情報の受信をご希望される場合は、下記のAdjustプレースホルダをコールバックの文字列に追記されることを推奨します。

  • {outdated_tracker} - ユーザーの最初のアトリビューションにおけるトラッカートークン
  • {outdated_tracker_name} - ユーザーの最初のアトリビューションにおけるトラッカー名
  • {attribution_updated_at} - 改訂されたアトリビューションのタイムスタンプ
  • {activity_kind} - インストールのアップデートinstall_update もしくは リアトリビューションのアップデートreattribution_update

注意:

  • 更新されたアトリビューションやリアトリビューションの情報は2017年3月から提供開始いたします。
  • 更新されたアトリビューションやリアトリビューションのコールバックはアトリビューション情報とAdjustのポレースホルダデータのみを含めます。

2.2グローバルコールバックの利用

追加として特定のコールバックをそれぞれのイベントごとに指定する際は、グローバルコールバックも同時に指定することができます。グローバルコールバックはクリック、インプレッション、セッション、インストール、リアトリビューションや拒否されたインストールなど、 すべて のイベントで発生します。

コールバックは同じプレースホルダを使用して、他のコールバックと変わらない動作をします。

グローバルコールバックはそれぞれのアプリ設定の > ローデータエクスポート > リアルタイムコールバック から、 ページ下部にある「グローバルコールバックを編集する」ボタンを選択していただき、そちらから追加していただけます。

設定していただいたコールバックに追加する形でグローバルコールバックも発生します。もしグローバルコールバックを指定し、同じコールバックURLを特定のイベントにも使用される場合は、二重でコールバックが発生します。グローバルコールバックとして一回、そして特定イベントのコールバックとして二回目が送られます。

下記のプレースホルダーをご利用いただくことでコールバックを別のイベントとして区別することができます。

{activity_kind}　クリック、インプレッション、承認と拒否 両方のインストール、セッション、リアトリビューション、アンインストール、リインストール、リアトリビューション　リインストール、イベントそして費用の更新など、どこからコールバックが発信されたか区別することができるアクティビティーの種類 {event}　イベントトークンと配置換えされたイベント; {event_name}, イベント名と配置換えされた際のイベント名

特定のタイプのアプリ内のイベントを独自に特定する為には、{event}をお使いください。{event_name} は読みやすい名前のラベルを受信できるようにご使用ください。イベントトークンは固定されますが、イベント名はいつでも変更可能です。その為イベント名そのものはIDとしての使用には向いていません。

3ベストプラクティス：Adjustのアトリビューションデータへの外部からのアクセス

アプリ内分析、内部のユーザー記録、大規模なBIシステムといった、他のソースから取集したデータを、Adjustのアトリビューション データと組み合わせられれば便利な場合が多くあります。

そのためには、まずコールバックの受信側のURLを指定する適切なエンドポイントを決定または作成し、パラメータの値が記録されるサーバーにデータを送信する必要があります。データの送信には、パラメータをデータベースに書き込むだけの単純なサーバー スクリプトや、より拡張された設定を使って計算を開始させる方法など様々な種類があります。

また、お客様側で記録したいデータの範囲、Adjust側でデフォルトで利用できる内容、SDKのカスタム パラメータを使用して補完すべき内容を決める必要があります。これについての答えは、主にどのような分析や仕組みをこのデータセットに実行することを検討しているかによって決まります。Adjustは負荷の大きい計算の多くをすでに実行しており、集計データに関するレポートを、オンライン表示やエクスポート機能により提供しています。

受信データは、特定のクリック、インストール、イベントが行ごとに示されるピボットテーブルのようなものだと考えてください。この表のそれぞれの行に、受信時刻、作成時刻、何らかの形式によるユーザーIDやデバイスID、データにより実行されたアクションが記録されることになります。

内部ユーザーIDをAdjustのアトリビューションデータと関連付けることを検討しているとします。この2つを関連付けることで、オンライン利用履歴やより詳細な購入パターンといった、その他のソースの内部記録を関連付けることができます。次のような視点から、カスタマイズされた分析を行うとよいでしょう。

  • 特定の集団から獲得した顧客は、返品率が多少高くなる可能性があるのか？
  • リターゲティングを行ったユーザーは、リターゲティングの前後でアプリをアクティブに使用していたと思われるか？

通常だと、単純なエンドポイントを作成して1つのユーザーアクションを記録し、内部システムで照会することになります。ユーザーIDをカスタム パラメータとしてSDKに追加し、Adjustダッシュボードでコールバックを定義して、デバイスIDとトラッカー名を送信できます。こうすることで、システムの内部記録を、モバイルで行われたすべての購入、登録、レベル達成、追跡中のその他のアプリ内イベントと関連付けることができます。

4ダイナミックコールバックパラメータを使ってカスタムデータを送信する

ダイナミックコールバックパラメータ(DCP)を使うと、クリックやインストール、リアトリビューション、セッション、イベントのカスタムパラメータをいくつでも送信できます。Adjustがサポートしている以上のパラメータをネットワークで使用している場合、もしくはユーザー特有のデータを追加で必要とする場合は、DCPを活用できます。

DCPはクリック、インストール、リアトリビューション、そしてイベントのコールバックのクリックURLにのみ利用できます。

手順

  1. パラメータ名を決めてください (例: campaign_name_3)
  2. 先頭にdcp_を追加し、クリック、インストール、リアトリビューションまたはS3コールバックのプレースホルダに設定してください。(例: {dcp_campaign_name_3})
  3. dcp_を除いたこのパラメータを、クリックトラッカーURLに追加してください。(例: campaign_name_3={campaign_macro})
  4. クリックトラッカーURLをアドネットワークに提出し、それらのネットワーク側で連携するよう依頼してください。

Adjustがこれらのパラメータ内のデータを受信すると、この情報はRawデータコールバックに送信されます。

5ベストプラクティス：コールバックを使用してユーザーに特典を与える

ユーザーの獲得戦略には、獲得チャネルがパフォーマンス マーケティング、アフィリエイト、または口コミのいずれであっても、アトリビューションの仕組みが必要です。友人を招待してサービスに登録させたユーザーに対して見返りを与えるには、同知ればいいでしょうか？

「SNS、メール、チャットで友達招待して、アプリで特典や割引をゲットしよう。」この様な設定は簡単に行うことができます。adjustはソースと獲得顧客をリンク付けるように設計されています。コールバックを使用して、Adjustのデータを結びつければ、コイン、VIPステータスやユーザーに約束した内容を提供することも可能になります。

ワークフローの例を以下に説明します。

  1. ユーザーの1人であるボブが、アプリを使って甥のトムを招待します。トムは、AdjustのトラッカーURL経由で招待されます。この例では「f0ob4r」のIDを付けた標準のトラッカーをダッシュボードに作成して、ユーザーIDをクリックラベルとして追加できます（キャンペーン構造とトラッカーの作成についてはトラッカーの作成についてをご参照ください）。 
     https://app.adjust.com/f0ob4r?label=[user_id]

  2. アプリによって、[user_id]がボブのIDに置き換えられ、Adjustのリンクがメール、SMSまたはSnapchat経由でトムに送信されます。トムがリンクをクリックすると、トムのクリックがAdjustによってボブの招待に帰属されます。

  3. トムがアプリをインストールすると、このインストールがAdjustによってボブに帰属されます。サーバーはボブのユーザーIDを含むコールバックを（{label}プレースホルダ経由で）受信します。

  4. トムがアカウント登録をすると、ボブとトムの双方のユーザーIDを含むコールバックを （カスタムSDKのパラメータ経由で）受信します。

  5. ボブに特典を与えるために必要なデータがすべてサーバーに揃ったため、サーバーがトムをボブの友人リストに自動的に追加し、紹介プログラムの成果を分析します。

また、SDKのデリゲートコールバックを使用えば手順3のようにラベルにアクセスして、両方のデータを瞬時にアプリ内に受信し、それをもとにさらなるロジックを実行することができます。

特定の実装ついて質問があれば、support@adjust.comまでお気軽にお問い合わせください。

6参考：コールバックのタイミング、応答、トラフィック負荷の評価

adjustは、リアルタイムなコールバックを提供するシステムです。Adjustのシステムでイベントが発生するたびに、登録されたすべてのコールバックの、そのイベントに対する起動の有無がシステムでチェックされます。これには、クライアント コールバック、有効化されたあらゆるパートナー、オープンなポストバックAPIにフックされたあらゆるトラフィック パートナーが含まれます（コールバック経由でパートナーが受信できるデータについての詳細は特別なパートナーまたはネットワーク統合ガイドをご参照ください）。

このイベントのデータを受信した数秒以内にコールバックが確実に発動します。インストールやイベントごとに、必要なコールバックをいくつでも発生させることができます。コールバックをいくつでもダッシュボードに入力し、任意の数のパートナーを有効化できます。また、クリックURLに複数のコールバックを追加できます。

コールバックサーバーは、エンドポイントのHTTPレスポンスを記録しますが、リダイレクトは追跡しません。または、エンドポイントからHTTP500 やHTTP400などのエラーコードが返された場合はコールバックを再試行します。しかし、エンドポイントから意味のあるレスポンスが返された場合は、adjustのサポートチームがお客様の問題を解決する役に立ちます。

サーバーに必要な処理速度やデータ送信量を検討するには、アプリのユーザー数から逆算する必要があります。登録などの1回限りのイベントだけを追跡する場合は、コンバージョンユーザー1人に対してコールバック1回というように、マーケティング活動と直接関連してコールバック数が決まります。コンバージョンイベントのコールバックによって、顧客のサーバーに高負荷がかかることは、普通ありません。

6.1AdjustコールバックIPのホワイトリスト管理

さらなるセキュリティ対策として、Adjustが用いる特定の範囲のIPアドレスにコールバックの受信を制限することができます。こうすることで、Adjustのサーバーを一意に識別し、Adjust以外のソースから偽装データを受信するような事態を回避できます。

Adjustのコールバックはすべて、以下の2つのサブネットから実行されます。これらを、受信側のサーバーで作成するホワイトリストに追加できます。

178.162.216.64/26
178.162.216.128/26

これはサブネット式の表記です。IPアドレスの範囲を展開したリストはこちらをご参照ください。

7参考：URLパラメータの追加

URLパラメータは、特定の名前が付けられ、ほとんどのサーバーが認識できる特別な構文で送信される値です。標準的なGET構文は以下のとおりです。

http://callbacks.myserver.com/path?parameter_one=value_one&parameter_two=value_two

パラメータはURLのパスの後に追加できます。クエスチョンマークの直後に最初のパラメータの名前を記述し、イコールの後にその値を記述します。例えば、「ip_address=192.168.1.1」と記述します。後続のパラメータはアンパサンドで区切って追加します。

お客様のサーバーで処理できるものであれば、パラメータはいくつでもURLに追加できます。

URLにパラメータを追加したい場合は、最後の値の後にアンパサンドを追加し、その後にパラメータの名前を入力し、さらにその後にイコールを追加してパラメータの値をイコールの後ろに入力します。また、動的なパラメータを使用するケースも多くみられます。この場合、プレースホルダを使用できます。プレースホルダは中かっこで括られた文字列で、動的な値を挿入するようAdjustのサーバーに指示します。

http://callbacks.myserver.com/path?campaign=12346&tracker_name={tracker_name}&idfa={idfa}

クエスチョンマークとアンパサンドが持つ特別な意味を考慮することが重要です。記号の挿入箇所を間違えるとコールバックが正しく解釈されない可能性があります。詳しくはエンコードのセクションをご参照ください。

問題があってパラメータ値を正しく受信できない場合は、以下の項目を確認してください。

  • 特殊文字が正しい箇所に挿入され、エンコードされていない。
  • 誤挿入されたアンパサンドやスペースといった、エンコードされていない特殊文字や意図しない特殊文字が挿入されていない。
  • プレースホルダの名前が以下のセクションの説明通りに正しい。
  • 使用しているプレースホルダがコールバックの要求時に利用可能なものである（例えば、クリック コールバックではデバイスIDを通知できません）。 ­ パラメータの名前が正しい。

普通、パラメータの順番は受信に影響しません。

8参考：カスタムSDKパラメータ

Adjustから取得したデータを、自身のSDKで利用できる追加パラメータでも拡張利用したい場合あります。このパラメータをカスタム パラメータといいます。カスタム パラメータは、Adjust SDKからAdjustのサーバーに送信されたのち、Adjustのサーバーからエンドポイントに送信されます。

カスタム パラメータは、trackEvent コールにパラメータ辞書を追加してアプリに実装します。このコールの作成方法の詳細な例は、SDKのreadmeで確認できます。

例えば、購入イベントに追加されたSDKから、ユーザーIDをカスタム パラメータとして送信している場合、「ユーザー123456の購入を追跡」という意味の文字列を記述し、売上イベントのエンドポイントとして、ダッシュボードに以下のようなURLも定義しています。

http://myserver.com/revenue/?tracker={trackerName}

追加のカスタム パラメータを使用して購入が追跡されると、カスタム パラメータがポストバックURLに自動的に追加されます。

パラメータをダッシュボードで指定することはできません。カスタム パラメータはダッシュボードで入力された文字列に自動的に追加されます。辞書のキーがパラメータの名前となり、パラメータ値はこのキーの値をとります。

この場合、Adjustによって購入が計測されるたびに、コールバックを即座に受信することになります。

http://myserver.com/revenue/?tracker=name_of_the_tracker_encoded&userID=123456

Adjustのサーバーは、エンドポイントの名前やパスに関係なく、正しい区切り記号や構文を知的に追加します。

カスタム パラメータは、購入イベントや登録イベントのユーザーID、購入用の製品ID、アプリ内の特定箇所の現在のステータスなど、追跡されたイベントに関して必要なデータを追跡するときに最も効果を発揮します。

パラメータはインストール後のイベントにのみ追加できます。ユーザーはインストール前にアクションを実行できないため、インストール時に送信する必要のあるパラメータはほとんどありません。必要と思われるパラメータは、利用可能なプレースホルダですでに対応されているはずです。

9参考：エンコード処理

エンコード処理は、複雑なパラメータを追加してでも、URLの構造を正しく維持するために必要です。値としてのURL、通貨記号、メールアドレスなどのパラメータに複雑な文字列を追加する場合は、こうしたパラメータをエンコードして最大限のセキュリティを確保する必要があります。エンコード処理によって、慎重に扱うべき文字列が慎重に扱う必要のない文字列に置き換えられます。この慎重に扱う必要のない文字列は、サーバーが正しく解釈できるパーセント記号とその後に続く2文字で通常構成されています。

ダッシュボードのコールバック フィールドに静的なパラメータを追加する場合は、アルファベットと数字以外の文字が含まれていないことを確認します。含まれている場合は、この文字列を最初にエンコードします。ただし中かっこ（{ または }）を用いたadjustのプレースホルダはエンコードしないでください。スペースなどは、コールバックに入力する前にエンコードする必要があります。URLのエンコード処理に使用できるエンコード ツールはネットで簡単に入手できます。

以下のようなコンテンツのみをエンコードし、URL構造自体はエンコードしないでください。

安全でないURL 

http://callbacks.myserver.com/registration?username=Bob Uncle&email=bob.uncle@mail.com&website=http://www.bobuncle.com

エンコード処理を施したURL 

http://callbacks.myserver.com/registration?username=Bob%20Unclde&email=bob.uncle%40mail.com&website=http%3A%2F%2Fwww.bobuncle.com

多くのサーバーやシステムでは、受信するURLのパラメータをデコードするのが慣例となっています。コールバックを完全に有効にする前に、お客様のサーバーでも受信するURLのパラメータを必ずデコードできるようにしてください。

SDKのカスタム パラメータもエンコードし、サーバーでの受信時にデコードされるよう設定する必要があります。

10参考：利用可能なプレースホルダ

adjustのウェブサイトに、利用可能なデータの最新のリストが常に公開されています。

11条件付きののコールバックフィルタリングまたは変更

プレースホルダを使えば、プレースホルダの値に応じて条件付きコールバックを決定し、コールバックURL全体を変更することもできます。例えば、環境（ProductionまたはSandboxのどちらからイベントを受信しているか）、デバイスタイプ、その他の利用可能なプレースホルダに応じて、コールバックをフィルター処理できます。

フィルタリングは、それぞれのコールバックの前に接頭辞を追加し、equal,{placeholder},value,callbackを記述し、プレースホルダ、期待値、コールバックを置き換えることで実行できます。例えば、以下をコールバックとしてダッシュボードに追加すると、Sandboxのイベントがテスト用サーバーに送信され、Releaseのイベントが製品版のサーバーに送信されます。

equal,{environment},sandbox,http://test.your-server.com?source={tracker_name} equal,{environment},production,http://production.your-server.com?source={tracker_name}

この構文であれば、あらゆるプレースホルダ、値およびコールバックを使用できます。

以下のように、値を連結することもできます。

equal,{environment}{device_type},sandboxtablet,http://test.your-server.com?source={tracker_name}   equal,{environment}{device_type},productiontablet,http://production.your-server.com?source={tracker_name}

ただし、equal以外の演算子はサポートされていません。