매개변수 빌드 도구 라이브러리
Meta는 클라이언트 측(JavaScript)과 서버 측(PHP, Java, Python, NodeJS, Ruby) 모두의 라이브러리 SDK 리스트를 제공했습니다. 이러한 SDK 라이브러리는 개발자가 전환 API 이벤트 매개변수(예: fbc 및 fbp)의 품질을 개선하도록 돕고, 광고주가 이러한 매개변수의 생성에 관한 Meta의 모범 사례를 준수하도록 하는 것을 목적으로 합니다.
이 문서에는 두 라이브러리에 대한 개요, 사용할 라이브러리에 대한 지침, 사용 사례 예시가 포함됩니다.
라이브러리 개요
클라이언트 측: 라이브러리와 이벤트가 브라우저 측의 프론트엔드에 있습니다. 라이브러리는 JavaScript로 구현됩니다. 개발자는 웹 페이지에 라이브러리를 직접 통합할 수 있습니다.
서버 측: 라이브러리와 이벤트가 서버 측의 백엔드에 있습니다. 백엔드에서 사용하는 언어에 따라 Meta에서 다른 언어(PHP, Java, Python, NodeJS, Ruby)로 된 라이브러리를 제공합니다.
라이브러리 선택
모든 라이브러리는 독립적으로 작동할 수 있습니다. 귀하 또는 귀하의 고객을 위한 잠재력을 극대화하려면 여기에서 권장 사항을 검토하세요.
기능별로 분류할 때, Meta에서 지원하는 라이브러리에는 두 가지 유형이 있습니다.
- 기본 라이브러리 parambuilder
- 확장 라이브러리 paramshelper
기본 라이브러리: parambuilder
Parambuilder는 Meta 개발자 문서에 언급된 모범 사례를 준수합니다. Parambuilder는 클라이언트 측(JavaScript)과 서버 측(PHP, Java, Python, NodeJS, Ruby)에 구현됩니다.
- 서버 측의 경우 서버 측 매개변수 빌드 도구 온보딩 가이드를 참조하세요.
- 클라이언트 측의 경우 클라이언트 측 매개변수 빌드 도구 온보딩 가이드를 참조하세요.
확장 라이브러리: paramshelper
Paramshelper는 clientParamsHelper라고도 하는데, 프론트엔드 클라이언트 측에서만 작동합니다. Paramshelper는 앱 내 브라우저에서 백업 clickID를 가져오는 JavaScript 라이브러리입니다. 이 라이브러리는 fbc 수집량과 품질(즉, 전체 이벤트 수 대비 fbc가 포함된 이벤트 수의 백분율)을 향상하는 데 도움이 될 수 있습니다.
- 클라이언트 측의 경우 클라이언트 측 매개변수 빌드 도구 온보딩 가이드를 참조하세요.
Paramshelper는 독립적으로 작동할 수 있지만, 서버 측 매개변수 빌드 도구 SDK로 보완하여 잠재력을 최대로 높이는 것이 좋습니다.
참고용 사용 사례 예시
솔루션을 빌드할 때 고려할 만한 사용 사례는 다음과 같습니다.
권장: 서버 측 매개변수 빌드 도구 + 클라이언트 측 paramshelper
서버 측 매개변수 빌드 도구와 클라이언트 측 paramshelper를 결합하면 높은 fbc 커버리지를 달성할 수 있는 가능성을 극대화하는 데 도움을 줄 수 있습니다.
그렇게 하려면 두 라이브러리(서버 측 ParamBuilder와 ClientHelper)를 함께 통합해야 합니다.
워크플로 예시:
- ClientParamsHelper 호출이 페이지를 읽어들일 때 클라이언트 측에서
decorateUrl(existing_url)을 대기합니다. - 클라이언트 측에서는, 가져오기 API(또는 다른 프론트-백엔드 통신)가 전체 URL(예: example.com?fbclid=xxxxx)을 포함하여 백엔드 서버를 호출합니다.
- 서버 측에서는, 수신자 엔드포인트(예: ExampleController)에서 선택한 언어에 따라 서버 라이브러리를 통합합니다.
- 자세한 내용은 서버 측 매개변수 빌드 도구 온보딩 가이드, 클라이언트 측 매개변수 빌드 도구 온보딩 가이드 또는 이들 문서 내에 링크된 README 파일을 참조하세요.
// 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")); // 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
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();
// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
....
클라이언트 측 ParamBuilder + ParamsHelper
클라이언트 측 라이브러리와 통합하고 싶다면 parambuilder를 사용하여 모든 기능을 포함할 수 있습니다.
예: 클라이언트 측 ParamBuilder(clientParamBuilder)만 통합합니다.
현재는 페이지를 읽어들일 때 API processAndCollectAllParams(url)을 지원합니다. 이는 fbc 및 fbp 쿠키를 가져오고 저장하기 위해 clientParamBuilder와 clientParamsHelper의 기능을 모두 활용합니다.
워크플로 예시:
- clientParamBuilder 라이브러리는 페이지를 읽어들일 때 processAndCollectAllParams(url)로 호출됩니다.
- 요청은 서버 측으로 전송됩니다. 그러면 서버에서 쿠키로부터 fbc, fbp를 읽을 수 있습니다.
서버 측 ParamBuilder만
자세한 예시는 서버 측 매개변수 빌드 도구 온보딩 또는 문서 내에 링크된 README 파일을 참조하세요.
워크플로 예시:
- 서버 측 엔드포인트에서 관련 언어 및 프레임워크에 따라 ParamBuilder 라이브러리를 가져옵니다.
- paramBuilder.processRequest를 호출하여 권장하는 업데이트된 쿠키의 리스트를 가져옵니다.
- 쿠키를 응답으로 설정합니다.
- paramBuilder.getFbc() 및 paramBuilder.getFbp()를 사용하여 fbc 및 fbp를 전환 API의 호출로 설정합니다.
클라이언트 측 ParamBuilder만
자세한 예시는 클라이언트 측 매개변수 빌드 도구 온보딩 가이드 또는 문서 내에 링크된 README 파일을 참조하세요.
워크플로 예시:
- 랜딩 페이지를 읽어들일 때 clientParamBuilder.processAndCollectParams(url)을 호출합니다.
- 그러면 요청이 서버 측으로 전송됩니다. 그러면 서버에서 쿠키로부터 fbc 및 fbp를 읽을 수 있습니다.
- 참고: 랜딩 URL에 fbclid가 없을 경우 fbc가 누락될 수 있습니다. 이는 예상되는 동작입니다.
모범 사례
- 웹페이지의 고객 정에서 최대한 이른 단계에
_fbp및_fbc쿠키를 저장합니다. 랜딩 페이지를 읽어들일 때_fbp및_fbc쿠키를 가져오는 것이 좋습니다. 하향 퍼널 이벤트일 때만 가져오거나 특정 이벤트가 트리거될 때 가져오는 것은 권장하지 않습니다. _fbc또는_fbp쿠키를 재정의하거나 조정하지 마세요._fbc는 대소문자를 구분하므로_fbc를 소문자로 정규화하거나 형식을 지정하지 마세요.- 라이브러리가 모바일, 데스크톱, 브라우저, 추적하고자 하는 도메인 등 모든 환경에 적용되도록 하세요.
- 서버 측 라이브러리는 백엔드에 사용되고, 클라이언트 측 라이브러리는 프론트엔드 브라우저 측에 사용됩니다. 개발자가 웹 페이지에 클라이언트 측 라이브러리를 직접 통합할 수 있지만, 서버 측 라이브러리는 서버 백엔드 측에서 호출됩니다. 클라이언트 측은 JS로만 제공되지만, Meta에서는 서버 측 라이브러리의 경우 여러 언어(PHP, Java, Python, NodeJS, Ruby)로 라이브러리를 제공합니다.