Skip to main content

​
How to install

Add the package to your composer.json file as a dependency:
Bash
composer require fingerprint/server-sdk
Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).
PHP
<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Fingerprint\ServerSdk\Api\FingerprintApi;
use Fingerprint\ServerSdk\Configuration;

$config = new Configuration(
  "SECRET_API_KEY",
  // Configuration::REGION_EUROPE
);
$client = new FingerprintApi($config);

// Search events, for example, by visitor ID
try {
  $events = $client->searchEvents(10, visitor_id: "VISITOR_ID");
  print_r($events);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}

// Get a specific identification event
try {
  $event = $client->getEvent("EVENT_ID");
  print_r($event);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}

​
Migration guide for PHP SDK v7

Version 7 migrates the SDK from Server API v3 to v4. This is a breaking change. This section summarizes the most important changes from previous versions. PHP SDK v7 requires PHP 8.2 or higher. Support for PHP 8.1 has been dropped.

​
Package and namespace rename

The Composer package changed from fingerprint/fingerprint-pro-server-api-sdk to fingerprint/server-sdk, and the namespace changed from Fingerprint\ServerAPI to Fingerprint\ServerSdk.
composer.json
"require": {
  "fingerprint/fingerprint-pro-server-api-sdk": "^6.10.0"
  "fingerprint/server-sdk": "^7.0.0"
}
Update all use statements to the new namespace:
PHP
use Fingerprint\ServerAPI\Configuration; 
use Fingerprint\ServerSdk\Configuration;

​
Client construction

The API key is now required in the Configuration constructor. Configuration::getDefaultConfiguration() and setDefaultConfiguration() have been removed. The FingerprintApi constructor also takes the configuration as its first argument, with the optional HTTP client second.
PHP
$config = Configuration::getDefaultConfiguration("SECRET_API_KEY", Configuration::REGION_EUROPE); 
$client = new FingerprintApi($httpClient, $config); 
$config = new Configuration("SECRET_API_KEY", Configuration::REGION_EUROPE); 
$client = new FingerprintApi($config, $httpClient); 
// OR if you are using the default HTTP client
$client = new FingerprintApi($config);

​
Get an event

The getEvent parameter $request_id is now $event_id, and the method returns an Event instead of a list($event, $response) tuple. The event data structure is flatter: fields are accessed directly instead of through the products wrapper.
PHP
list($event, $response) = $client->getEvent(request_id: "REQUEST_ID"); 
$visitorId = $event->getProducts()->getIdentification()->getData()->getVisitorId(); 
$event = $client->getEvent(event_id: "EVENT_ID"); 
$visitorId = $event->getIdentification()->getVisitorId();
If you need the raw HTTP response, use the WithHttpInfo variant. Every operation now exposes {operation}(), {operation}WithHttpInfo(), {operation}Async(), and {operation}AsyncWithHttpInfo() methods.
PHP
list($event, $response) = $client->getEvent("REQUEST_ID"); 
list($event, $response) = $client->getEventWithHttpInfo("EVENT_ID");

​
Search events

searchEvents now returns an EventSearch object instead of an array.
PHP
list($events, $response) = $client->searchEvents(10, visitor_id: "VISITOR_ID"); 
$events = $client->searchEvents(limit: 10, visitor_id: "VISITOR_ID");

​
getVisits and getRelatedVisitors replaced by searchEvents

getVisits and getRelatedVisitors have been removed. Use searchEvents with the visitor_id to find the events for a particular visitor.
PHP
list($visits, $response) = $client->getVisits("VISITOR_ID"); 
$events = $client->searchEvents(limit: 10, visitor_id: "VISITOR_ID");

​
Update an event

updateEvent now takes the event ID first and an EventUpdate body second, returns void instead of an array, and issues a PATCH request instead of PUT.
PHP
$body = new EventsUpdateRequest(['tag' => ['key' => 'value']]); 
$client->updateEvent($body, request_id: "REQUEST_ID"); 
$body = new EventUpdate(['tags' => ['key' => 'value']]); 
$client->updateEvent(event_id: "EVENT_ID", $body);

​
Handling sealed client results from a v3 JavaScript agent

PHP SDK v7 will fail to deserialize the decrypted payload of a sealed client result sent by a v3 JavaScript agent into an Event because the payload is an EventsGetResponse (i.e., the v3 event format), not an Event. In this case, Sealed::unsealEventResponse throws an InvalidSealedDataException. To upgrade to PHP SDK v7 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails. To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the sealed client results guide. Both Sealed::unsealEventResponse and $client->getEvent return an Event, so the fallback returns the same type.
PHP
// Partial example (imports omitted).

function getEvent(
  FingerprintApi $client,
  string $sealedResultBytes, // previously decoded using base64_decode
  string $eventId,
  array $keys
): Event {
  // Try to unseal the payload locally first.
  try {
    return Sealed::unsealEventResponse($sealedResultBytes, $keys);
  } catch (InvalidSealedDataException $e) {
    // Deserialization failed. Fall back to the Server API using the event ID
    // sent alongside the sealed client results.
    fwrite(STDERR, sprintf("Could not unseal result, falling back to Server API: %s\n", $e->getMessage()));
    return $client->getEvent($eventId);
  }
}

​
Documentation

You can find the full documentation in the official GitHub repository.