コンバージョンAPI

パラメータービルダーライブラリ

Metaは、クライアントサイド(JavaScript)とサーバーサイド(PHP、Java、Python、NodeJS、Ruby)の両方のライブラリSDKのリストを提供しています。これらのSDKライブラリは、開発者がコンバージョンAPIイベントパラメーター(例えば、fbc、fbp、client_ip_address、emやphなどの顧客情報パラメーター)の品質を改善するのを助け、広告主がこれらのパラメーターの生成に関するMetaのベストプラクティスに従うことができるようにするためのものです。

このドキュメントには、これら2つのライブラリの概要、使用するべきライブラリに関するガイダンス、活用事例が含まれています。

ライブラリの概要

クライアントサイド: ライブラリとイベントは、ブラウザーサイドのフロントエンドにあります。ライブラリは、JavaScriptで実装されています。開発者はこのライブラリを自分のウェブページに直接統合できます。

サーバーサイド: ライブラリとイベントは、サーバーサイドのバックエンドにあります。Metaでは、バックエンドで使う言語に応じて、さまざまな言語(PHP、Java、Python、NodeJS、Ruby)のライブラリを用意しています。

ライブラリの選択

どのライブラリも単独で動作可能です。ただし、ご自身や顧客の環境で最適な結果を得るために、以下の推奨事項を確認してください。

Parambuilderは、Metaの開発者向けドキュメントに記載されているベストプラクティスに従っており、クライアントサイド(JavaScript)とサーバーサイド(PHP、Java、Python、NodeJS、Ruby)で実装されています。

参照用の活用事例

ソリューション構築の際には、以下の活用事例を参考にすることができます。

推奨: サーバーサイドパラメータービルダー + クライアントサイドパラメータービルダー

サーバーサイドとクライアントサイドのパラメータービルダーを組み合わせることで、fbcおよびIPv6のカバレッジを高水準で実現する可能性を最大化できます。

そのためには、2つのライブラリ(サーバーサイドパラメータービルダーとクライアントサイドパラメータービルダー)を統合する必要があります。




ワークフローの例

  • 広告主のクライアントアプリがクライアントサイドパラメータービルダーを読み込み、提供されているAPI「processAndCollectAllParams」をgetIpFn関数ポインターとともに呼び出します。
  • 提供されたgetIpFn関数が呼び出され、実際のgetIpFnの実装内容に応じて、広告主が設定したエンドポイントからIPv6アドレスを取得します。
  • 広告主が用意したエンドポイントから返されたIPv6アドレスは、getIpFnの戻り値からクライアントサイドパラメータービルダーに渡され、後で再利用できるように、キー_fbiのCookieに保存されます。
  • クライアントサイドでは、ファーストパーティCookieを含めて、フェッチAPI (またはその他のフロントバックエンド通信)で通常どおりバックエンドサーバーとの通信を開始します。
  • サーバーサイドでは、受信エンドポイント(例: ExampleController)で、使用言語に対応したサーバーサイドライブラリを統合し、提供されているAPI「processRequest」を呼び出してリクエストを処理します。
  • processRequest APIは、クライアントサイドで更新すべき推奨Cookieのリストを返します。
  • レスポンスヘッダーに推奨Cookieを設定して、クライアントブラウザーにそのCookieを保存するよう指示します。
  • getFbc()、getFbp()、getClientIpAddress()、getNormalizedAndHashedPII()など、提供されているさまざまなAPIを呼び出します。
  • SDKは、fbc、fbp、client_ip_address、メールアドレス、電話番号など、さまざまな値を返します。
  • コンバージョンAPIを通じて、取得したそれらの値をMetaに送り返します。
// Example Controller which processes all requests to example.com
// Start process
ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList('example.com', 'yourDomain.com'));
// Input the request's full URL, such as: example.com?fbclid=xxxxx
// Process and get recommended updated cookie
List<CookieSetting> updatedCookieList =
        paramBuilder.processRequest(
            request.getHeader("host"),  // example.com
            request.getParameterMap(), // {'fbclid':['xxxxx']}
            cookieMap, 
            request.getHeader("referer"),
request.getHeader("X-Forwarded-For"),
request.getRemoteAddr(),
); // optional: referer full url


// Save cookie from server side
for (CookieSetting updatedCookie : updatedCookieList) {
      Cookie cookie = new Cookie(updatedCookie.getName(), updatedCookie.getValue());
      cookie.setMaxAge(updatedCookie.getMaxAge());
      cookie.setDomain(updatedCookie.getDomain());
      response.addCookie(cookie);
 }

// Get fbc, fbp, client_ip_address
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();
String client_ip_address = paramBuilder.getClientIpAddress();

// Get Normalized and Hashed PII like email and phone number
String normalizedAndHashedEmail = paramBuilder.getNormalizedAndHashedPII(‘John_Smith@gmail.com’,’email’);
String normalizedAndHashedPhone = paramBuilder.getNormalizedAndHashedPII(‘(650)555-1212’,’phone’);

// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
.setClientIpAddress(client_ip_address)
.setEmail(normalizedAndHashedEmail)
.setPhone(normalizedAndHashedPhone)
....

サーバーサイドParamBuilderのみ

サーバーサイドでのパラメータービルダーのオンボーディングガイド、またはそこからリンクされているREADMEファイルで、いくつかの詳しい例を参照してください。

ワークフローの例

  • サーバーのエンドポイントで、関連する言語とフレームワークに基づきParamBuilderライブラリをインポートします。
  • paramBuilder.processRequestを呼び出して、推奨されている更新済みCookieのリストを取得します。
  • 応答にCookieを設定します。
  • paramBuilder.getFbc()、paramBuilder.getFbp()、paramBuilder.getClientIpAddress()、paramBuilder.getNormalizedAndHashedPII()を使って、コンバージョンAPIの呼び出しにfbc、fbp、client_ip_address、その他のPII(メールアドレスや電話番号など)を設定します。

クライアントサイドParamBuilderのみ

クライアントサイドでのパラメータービルダーのオンボーディングガイド、またはそこからリンクされているREADMEファイルで、いくつかの詳しい例を参照してください。

ワークフローの例

  • ランディングページを読み込む際に、clientParamBuilder.processAndCollectAllParams(url, getIpFnl)を呼び出します。
  • すると、リクエストがサーバーサイドに送信されます。サーバーは、キー_fbc、_fbp、_fbiを使用して、Cookieからfbc、fbp、client_ip_addressを読み取ることができます。
    • 注: ランディングURLにfbclidが含まれていない場合、fbcが欠落している場合があります。これは、正常な動作です。

便利なリンク

メインのGithubリンク

最新バージョンを使用していることを確認してください。

ベストプラクティス

  • ウェブページのカスタマージャーニーのできるだけ早い段階で、_fbpと_fbcのCookieを保存するようにしてください。ランディングページを読み込む時点で、_fbpと_fbcのCookieを取得するのが理想的です。Cookieをファネル下層イベントでのみ取得したり、特定のイベントがトリガーされた時点でのみ取得したりすることは、おすすめしません。
  • _fbcまたは_fbpのCookieを、オーバーライドしたり調整したりしないでください。_fbcでは大文字と小文字が区別されます。_fbcの正規化や小文字への書式設定は行わないでください。
  • 追跡対象となるモバイル、デスクトップ、ブラウザー、ドメインなど、すべてのサーフェスにライブラリが適用されるようにしてください。
  • サーバーサイドライブラリはバックエンド用であり、クライアントサイドライブラリはフロントエンドブラウザー用です。開発者は、クライアントサイドライブラリを自身のウェブページに直接統合できます。一方、サーバーサイドライブラリは、サーバーサイドのバックエンドで呼び出されます。クライアントサイドはJavaScriptでのみ利用可能ですが、サーバーサイドライブラリはさまざまな言語(PHP、Java、Python、NodeJS、Ruby)に対応しています。
  • getIpFn機能を実装する際には、まずIPv6アドレスを取得してから、ユーザーのクライアントサイドからIPv6アドレス取得機能が利用できない場合にはIPv4アドレスにフォールバックすることをおすすめします。
  • パフォーマンスを最適化するには、クライアントとサーバーの両方のパラメータービルダーを統合することをおすすめします。クライアントサイドのパラメータービルダーを使ってclient_ip_addressを取得し、Cookieに保存できます。その後、サーバーサイドのパラメータービルダーを使って、Cookieとリクエストの両方から最適なclient_ip_addressを取得し、コンバージョンAPIを使ってMetaに送信できます。
  • 顧客情報パラメーターへの正規化およびハッシュ化処理は、MetaにコンバージョンAPI経由で送信する前に一度だけ実行することをおすすめします。これはクライアントサイドまたはサーバーサイドのいずれか一方で行ってください。
  • パラメータービルダーから返される顧客情報パラメーターフィールドの値はすべて、大文字と小文字が区別されます。これらの値は、正規化(例: 小文字化など)を行わずに、そのままコンバージョンAPI経由でMetaに送信できます。こうした処理は、パラメータビルダーSDKの内部処理の中で自動的に実行されているためです。

関連情報