PHP Server SDK

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.

JavaScript Agent

Server API

Automation Intelligence API

Policy and Upgrades

Device Reputation Network API

Management API

Server SDKs

How to install

Migration guide for PHP SDK v7

Package and namespace rename

Client construction

Get an event

Search events

`getVisits` and `getRelatedVisitors` replaced by `searchEvents`

Update an event

Handling sealed client results from a v3 JavaScript agent

Documentation

​How to install

​Migration guide for PHP SDK v7

​Package and namespace rename

​Client construction

​Get an event

​Search events

​getVisits and getRelatedVisitors replaced by searchEvents

​Update an event

​Handling sealed client results from a v3 JavaScript agent

​Documentation

How to install

Migration guide for PHP SDK v7

Package and namespace rename

Client construction

Get an event

Search events

`getVisits` and `getRelatedVisitors` replaced by `searchEvents`

Update an event

Handling sealed client results from a v3 JavaScript agent

Documentation