This document provides information on using the PHP SDK.

📘

Before You Read

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 user funnel analysis 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

20722072

Sequence

11001100

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 Funnel? (SDK functions after the set up)

Depending on whether you plan to perform an A/B test or create a funnel analysis 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.

Funnel Analysis: Apply Step 4.
In a funnel analysis, 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.
  • $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

👍

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.

In the example code below, we are passing the experimental 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
}

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.


Did this page help you?