This document provides information on using the PHP SDK.

📘

Before You Read

• If this is your first time working with an SDK, please refer to the What is a SDK? document

1. PREPARATIONS
The Hackle PHP SDK supports PHP 5.5 and later.

2. SDK key, experimental key, event key
This document assumes that you know the SDK key, experiment key, and event key.
Please read the Keys Used by SDK Functions document first for a better understanding.

PHP SDK Functions

Similar to the SDKs for the other languages, together with a Hackle Proxy, the PHP SDK also carries out two main functions:

*Traffic distribution
A function used in A/B testing assigns users to specific Test Groups, A, B, and C, and returns the information on the assigned groups of the users back to the server after distribution to keep a record of each user’s exposure.

Track and send user events
The track feature used in both A/B Testing and Data Analytics allows you to record the specific actions by users on the website/page/app and sends this information to Hackle to derive results from the experiment or carry out funnel analysis.

Managing User Identifiers

A user identifier is a value used to uniquely identify a specific user. The user identifier is used to uniquely identify a user to apply the SDK functions on.

For more information on the importance of user identifiers, please check out the Tracking and Identifying Unique Users

How is PHP different from other SDKs for other programming languages?

The PHP SDK is designed differently from other SDKs because of the “shared nothing” nature of PHP. Out of the several different languages, you are probably familiar with: JavaScript, Ruby, Python, Java, and R, only PHP offers a default Shared-Nothing Architecture. However, the PHP SDK also comes with limitations as it must be used alongside the Hackle Proxy for consistent setup information and low latency. Without the API functions provided by the Hackle Proxy, the PHP SDK can carry out no functions.

Hackle Proxy

The Hackle Proxy is a standalone service that provides all the SDK functionalities and features. The Hackle Proxy service provides integrated and simplified endpoints to access the features provided by the SDK through APIs.

For more information on the Hackle Proxy- check out the Hackle Proxy document.

PHP SDK + Proxy Structure

Sequence

SDK integration (actions required for set up)

SDK integration is required to apply the necessary SDK functions described above to your experiment.
This integration stage is broken down into steps 1 and 2 below, and these are the steps that must occur during the first integration.

In the case of React SDK, the user page visit event (URL) will be automatically collected from the point when the SDK integration is complete.

A/B or Data Analytics? (SDK functions after the set up)

Depending on whether you plan to perform an A/B test or perform Data Analytics of your website or app, there is a difference in the types of functions required to be implemented from the integrated SDK.

A/B test: The SDK functions are carried out in the order of Step 3 → Step 4.
(1) Traffic distribution function occurs on the A/B test performed.
(2) The data from the user event track function is sent to Hackle to measure the outcome or the designated metrics of an A/B test from the dashboard.

Data Analytics: Apply Step 4.
In a Data Analytics, the user events that need to be analyzed are tracked and sent to Hackle.

SDK integration

Step 1: Add Dependencies

Think of this step as importing our SDK into your code base. To use our Hackle services add the SDK as a dependency and import our SDK. You are introducing Hackle’s SDK into your code and your application will now have access to the Hackle SDK.

composer require hackle/hackle-php-sdk:0.0.1

Step 2: Initialize the SDK

Once you have added the dependencies and the importing is complete, in order to start using the Hackle SDK you must initialize the SDK.

Client instantiation

$config = ['base_uri' => 'your.proxy.server.uri'];
// Enter the SDK Key in the $sdkKey.
$hackleClient = \Hackle\Clients::proxy($sdkKey, $config);

Instantiate ProxyClient . When instantiating, it receives two parameters, $sdkKey and $config.

• $sdkKey: Use the server SDK key. The SDK key can be found in the SDK integration in the dashboard of Hackle service.
• $config: Input additional information of the proxy server.
  • base_uri: Enter the URL (scheme, host, port) of the executed proxy server. If not entered, it will be set to [<http://localhost:8888>](http://localhost:8888`)

👍

It is recommended to instantiate the Client once and reuse it throughout the application.

Application of SDK functions (Using the SDK)

• Note: The following SDK functions can only be carried out once the SDK integration is complete.

Step 3: Distribution of users into Test Groups (SDK)

This SDK function specifically applies to the A/B test only.
This function distributes users to test groups belonging to a specific experiment key, and writes logic for each test group.

📘

Test Group

The test groups are the different groups that users are distributed into. Users in Test Group A (control group) are shown the current version of the page and Test Group B, C, D, etc (experimental groups) are shown a different version of the page with proposed improvements. There can be more than one experimental group that can be set on the dashboard. For information on how to manage test groups, please refer to the test group document.

You can distribute users and receive results by passing the experiment key and user identifier to the $hackleClient->variation() method. Then implement a specific logic for each test group.

The experiment key is a unique number for each A/B test and can be found on the dashboard within the Hackle service.

In the example code below, we are passing the experiment key 42, and there are two test groups, A and B.

// Determines the test group to assign the user in an A/B tests with an experiment key of 42.
// For undetermined cases, the user is returned to test group A. 
$variation = $hackleClient->variation(42, $userId);

if ($variation == 'A') {
    // Logic for test group A
} elseif ($variation == 'B') {
    // Logic for test group B
}

📘

Deduplication of exposure event

If you use Backend-side SDK, Any successive Exposure events within one minute for same A/B test from single user will be counted as one.

Step 4: Track User Events

The SDK sends out user events back to the Hackle server for measurement and analysis of results.

User events can be tracked and sent by passing the event key and user identifier to the $hackleClient->track() method. If required, when sending a user event, you can put a numeric value in value and send it out together.

See the example below for a sample usage case. It is assumed that the event key is purchase and the user identifier is in $userId.

/* Example 1: Send only the event key */
$hackleClient->track('purchase', $userId);

/* Example 2: Send the event key and numeric value together */
$purchaseAmount = 320.0;
$hackleClient->track('purchase', $userId, $purchaseAmount);

Suppose you have defined an event key called 'purchase' to collect an event when the user presses the purchase button.
Example 1 is sending only the event key, and Example 2 shows an example where the purchase amount is put in the $purchaseAmount section to collect the purchase amount as well.