mktz/server-side-testing-sdk

PHP SDK for server-side-testing

v1.0.5 2025-04-29 06:52 UTC

Requires

• php: >=7.0
• ext-redis: *
• ext-zlib: *
• doctrine/annotations: ^1.4 || ^3.0
• guzzlehttp/guzzle: ^6.5|^7.0
• psr/http-client: ^1.0
• psr/log: ^1.1
• symfony/property-access: ^3.4 || ^5.0
• symfony/serializer: ^3.4 || ^5.0

Requires (Dev)

• phpunit/phpunit: ^6.0 || ^9.0

proprietary

• Omniconvert

README

Documentation

API Reference is available online at: http://docs.server-side-testing.omniconvert.com.s3-website-eu-west-1.amazonaws.com/

This documentation is automatically updated with each new release.

Installation

You can install the SDK via Composer:

composer require mktz/server-side-testing-sdk

Example of usage

use Omniconvert\ServerSideTestingSdk\Config\ClientConfig;
use Omniconvert\ServerSideTestingSdk\Config\RedisConnectionConfig;
use Omniconvert\ServerSideTestingSdk\Connection\RedisConnection;
use Omniconvert\ServerSideTestingSdk\Entity\Context\Context;
use Omniconvert\ServerSideTestingSdk\Entity\SessionParams;
use Omniconvert\ServerSideTestingSdk\ExploreClient;
use Omniconvert\ServerSideTestingSdk\Factory\StorageFacadeFactory;
use Omniconvert\ServerSideTestingSdk\Http\HttpClient;
use Omniconvert\ServerSideTestingSdk\Logger\DefaultLogger;
use Omniconvert\ServerSideTestingSdk\Logger\LoggerDumper;
use Omniconvert\ServerSideTestingSdk\Logger\LoggerFactory;
use Omniconvert\ServerSideTestingSdk\Security\UserProvider;
use Omniconvert\ServerSideTestingSdk\Service\DecisionManager;
use Omniconvert\ServerSideTestingSdk\Service\Tracker;
use Omniconvert\ServerSideTestingSdk\StorageDriver\ArrayStorageDriver;
use Omniconvert\ServerSideTestingSdk\StorageDriver\RedisStorageDriver;
use Omniconvert\ServerSideTestingSdk\Factory\ContextParamFactory as CP;
use Omniconvert\ServerSideTestingSdk\Factory\ContextBuilder;
use Omniconvert\ServerSideTestingSdk\Utils\Ga4CookieReader;

// Define app config
$userId = "00001"; // Unique user ID (from the DB) or any other unique identifier
$apiKey = ''; // Get it from https://web.omniconvert.com/api-credentials/
$env = 'dev';

// Step 1 - Build the dependencies
$storageFacade = StorageFacadeFactory::createWithDriver(
    new RedisStorageDriver(new RedisConnection(new Redis(), new RedisConnectionConfig("127.0.0.1", 6379)))
);

$httpClient = new HttpClient($apiKey, "https://app.omniconvert.com/", $env === 'dev');
// For production mode disable cache bypass, like this:
// $httpClient = new HttpClient($apiKey);

$sessionParams = (new SessionParams())
    ->setReferrerUrl('https://www.omniconvert.com/')
    ->setReferrerDomain('omniconvert.com')
    ->setReferrerType('referral')
    ->setLandingUrl('https://www.omniconvert.com/customer-lifetime-value-ecommerce-benchmark/')
    ->setDeviceType('desktop')
    ->setGa4TrackingId(Ga4CookieReader::readTrackingId())
    ->setGa4SessionId(Ga4CookieReader::readSessionId())
    // For all params see:
    // http://docs.server-side-testing.omniconvert.com.s3-website-eu-west-1.amazonaws.com/classes/Omniconvert-ServerSideTestingSdk-Entity-SessionParams.html
;
$userProvider = new UserProvider($storageFacade, $userId, $sessionParams);

// Step 1.1 - Optionals:
$clientConfig = new ClientConfig($storageFacade, ["reinit_timeout" => 600]);
$decider = new DecisionManager($storageFacade, $userProvider);

// Initialize Tracker with client and context
$tracker = new Tracker($httpClient, $userProvider);

// Step 2 - Initialize the client
$client = new ExploreClient(
    $httpClient,
    $storageFacade,
    $userProvider,
    $clientConfig,
    $decider,
    $tracker
);

// Step 3 - Add context params
// Using the ContextFactory:
$context = new Context(
    [
        CP::url("https://www.omniconvert.com/customer-lifetime-value-ecommerce-benchmark/"),
        //CP::screen("homepage"),
        CP::ip("127.0.0.1"),
        CP::custom("custom_param", "custom_value"),
        CP::utm([
            'source' => 'googlea',
            'medium' => 'cpc',
            'campaign' => 'campaign_name',
            'content' => 'content',
            'term' => 'term',
        ]),
        CP::userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"),
        CP::language("en-US"),
        CP::deviceType("desktop"),
        CP::resolution("1728x1117"),
        CP::browser("Chrome"),
        CP::browserLanguage("en-US"),
        CP::browserVersion("120.0.0.0"),
        CP::os("macOS"),
        CP::language("en-US"),
        CP::referrer("https://www.omniconvert.com/customer-lifetime-value-ecommerce-benchmark/"),
        CP::referrerType("referral"),
    ]
);

// Option 2: Using the fluent ContextBuilder
$context = ContextBuilder::create()
    ->url("https://www.omniconvert.com/customer-lifetime-value-ecommerce-benchmark/")
    // ->screen("homepage")
    ->ip("127.0.0.1")
    ->custom("vip_user", "yes")
    ->utm([
        'source' => 'googlea',
        'medium' => 'cpc',
        'campaign' => 'campaign_name',
        'content' => 'content',
        'term' => 'term',
    ])
    ->userAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36")
    ->language("en-US")
    ->deviceType("desktop")
    ->resolution("1728x1117")
    ->browser("Chrome")
    ->browserLanguage("zh-cn")
    ->browserVersion("120.0.0.0")
    ->os("macOS")
    ->language("en-US")
    ->referrer("https://www.omniconvert.com/customer-lifetime-value-ecommerce-benchmark/")
    ->referrerType("referral")
    ->resolution("1920x1080")
    ->build()
;
// Choose one of the options above and comment out the other

// Step 4 - Decide
$decisionList = $client->decide($context);

// Trigger goal with product SKUs
$details = [
    "transaction" => "1555",
    'skus' => ['PROD123', 'PROD456', 'PROD789']
];
$tracker->track("sale", 111, $details); // Required

$logs = LoggerFactory::getLogger()->getLogs(DefaultLogger::LOG_LEVEL_KEY_ALL);
LoggerDumper::dump($logs);

Local Environment for Development

These commands compile & spin up containers for local development and testing of the SDK.

Run

# Run container with default PHP version (7.0)
make run

# Run container with specific PHP version
make run phpv=8

Build

# Build image for default PHP version (7.0)
make build

# Build image for specific PHP version
make build phpv=8

Test

# Run tests using default PHP version (7.0)
make test

# Run tests using specific PHP version (7.0)
make test phpv=8