Go to Docs (EN)Sign in to Dashboard

PHP

Suggest Edits

이 문서는 PHP SDK를 사용하기 위한 정보를 제공하고 설명합니다.

📘

Before You Read

  • SDK 연동이 처음이라면, SDK 문서를 참고해주세요.

1. 사전 준비 사항
Hackle PHP SDK는 PHP 5.5 이상을 지원합니다.

2. SDK에서 사용되는 몇 가지 키
문서에서 언급되는 몇 가지 키가 있습니다. 각 키 개념 및 키를 확인하는 방법에 대해서는 SDK에서 사용되는 키 문서를 먼저 읽어주시기 바랍니다.

개요

PHP SDK 기능

SDK는 두 가지 주요 기능이 있습니다.

  • 테스트 그룹 분배
    A/B 테스트에서 사용하는 기능으로, 사용자를 A, B, C 등 특정 테스트 그룹으로 분배하여 할당하고 분배된 그룹을 반환합니다. 사용자가 A/B 테스트에 노출되었음을 기록하기 위해 할당된 그룹 정보를 핵클로 전송합니다.

  • 사용자 이벤트 전송
    A/B 테스트 목표 계산 및 데이터 분석에서 사용하는 기능으로, 사용자의 행동을 분석하기 위해 이벤트를 전송합니다.

사용자 식별자 관리

사용자 식별자는 사용자를 고유하게 식별하는 데 사용됩니다. 테스트 그룹 분배, 사용자 이벤트 전송 기능을 사용할 때 사용자 식별자를 같이 전달해야 됩니다.

사용자 식별자에 대한 자세한 정보는 사용자 식별자 관리하기에서 확인할 수 있습니다.

다른 SDK와의 차이점

PHP SDK는 PHP의 shared nothing 특성 때문에 다른 SDK와는 다르게 설계되었습니다. 일관된 설정 정보와 낮은 지연 시간을 위해 Hackle Proxy 서비스와 함께 사용해야 합니다.

Hackle Proxy

Hackle Proxy 서비스는 SDK 기능을 제공하는 독립 실행형 서비스입니다. Hackle Proxy 서비스는 API를 통해 SDK가 제공하는 기능에 엑세스하기 위한 통합 및 단순화된 엔드포인트를 제공합니다.

Hackle Proxy 문서에서 자세한 내용을 확인할 수 있습니다.

PHP SDK + Proxy 구조

2072

작업 순서

1141

SDK 연동

SDK 기능을 적용하기 위해 SDK 연동 작업이 필요합니다.
1단계 및 2단계가 이에 해당되며, 최초 연동 시 반드시 거쳐야 합니다.

A/B test or Data Analytics?

핵클 플랫폼 연동의 목적이 A/B 테스트인지 혹은 데이터 분석인지에 따라 적용해야 할 SDK 기능에 차이가 있습니다.

  • A/B 테스트: 3단계 → 4단계 순으로 적용합니다.
    (1) A/B 테스트를 진행할 곳에 테스트 그룹 분배 기능을 적용합니다.
    (2) A/B 테스트의 목표를 추적할 곳에 사용자 이벤트 전송 기능을 적용합니다.
  • 데이터 분석: 4단계를 적용합니다.
    분석할 이벤트가 발생하는 곳에 사용자 이벤트 전송 기능을 적용합니다.

SDK 연동

1 단계 : 의존성 추가

composer require hackle/hackle-php-sdk:0.0.3

2 단계 : SDK 초기화

Client 인스턴스화

$config = ['base_uri' => 'your.proxy.server.uri'];
// $sdkKey 자리에 SDK 키를 넣습니다.
$hackleClient = \Hackle\Clients::proxy($sdkKey, $config);

ProxyClient 를 인스턴스화 합니다. 인스턴스화 할 때 $sdkKey, $config 두개의 파라미터를 입력받습니다.

  • $sdkKey: Server SDK 키를 사용합니다.
  • $config: Proxy 서버의 정보를 추가로 입력 받아야 합니다.
    • base_uri: 실행시킨 Proxy 서버의 URI(scheme, host, port)를 입력합니다. 입력하지 않으면 http://localhost:8888 으로 설정됩니다.

👍

Client를 한 번 인스턴스화 하고 어플리케이션 전체에서 재사용 하는 것이 좋습니다.

SDK 기능 적용

  • 주의: SDK 연동이 완료된 후 SDK 기능을 적용할 수 있습니다.

3 단계 : 테스트 그룹 분배

A/B 테스트 전용 단계입니다.
특정 실험 키에 속한 테스트 그룹을 대상으로 사용자를 분배하고, 각 테스트 그룹에 해당하는 로직을 작성합니다.

📘

테스트 그룹

테스트 그룹은 테스트 대상이 되는 기존안(대조군)과 개선안(실험군)을 의미하며, 개선안은 1개 이상일 수 있습니다. 대시보드에서 설정 가능하며, 테스트 그룹을 관리하는 방법에 대해서는 A/B 테스트 설정 문서를 참고하시기 바랍니다.

$hackleClient->variation() 메소드에 실험 키와 사용자 식별자를 전달하면 사용자를 분배하고 결과를 전달받을 수 있습니다. 이후 테스트 그룹 별 로직을 구현합니다.

아래 예제 코드에서는 실험 키 42를 전달하고 있으며, 테스트 그룹은 A와 B 두 개가 존재합니다.

// 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
// 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
$variation = $hackleClient->variation(42, $userId);

if ($variation == 'A') {
    // 그룹 A 로직
} elseif ($variation == 'B') {
    // 그룹 B 로직
}

📘

노출 이벤트 중복 제거

PHP SDK를 사용하는 경우 동일한 사용자가 1분 이내에 연속으로 발생시킨 동일한 A/B 테스트 분배결과에 대한 노출 이벤트를 제거합니다. 1분 이내의 이벤트는 1회로 계산됩니다.

4 단계 : 사용자 이벤트 전송

결과 측정 및 분석을 위해 사용자 이벤트를 전송합니다.

$hackleClient->track() 메소드에 이벤트 키와 사용자 식별자를 전송할 수 있습니다. 필요한 경우 사용자 이벤트 전송 시 숫자 값을 함께 전송할 수 있습니다.

활용 사례에 대해서는 아래 예시를 참고합니다. 이벤트 키는 purchase 이며, 사용자 식별자는 $userId에 들어있다고 가정합니다.

/* 예시 1: 이벤트 키만 전송 */
$hackleClient->track('purchase', $userId);

/* 예시 2: 이벤트 키와 숫자 값을 함께 전송 */
$purchaseAmount = 320.0;
$hackleClient->track('purchase', $userId, $purchaseAmount);

사용자가 구매하기 버튼을 눌렀을 때 이벤트를 수집하기 위해 purchase 라는 이벤트 키를 정의했다고 가정합니다.
예시 1에서는 이벤트 키만 전송하고 있으며, 예시 2에서는 구매 금액을 함께 수집하기 위해 $purchaseAmount에 구매 금액을 넣은 사례를 보여주고 있습니다.

Updated 5 months ago