Fingerprint Pro Server API PHP SDK

Fingerprint Pro Server API allows you to get information about visitors and about individual events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device.

This PHP package is automatically generated by the Swagger Codegen project:

• API version: 3
  • Package version: 6.1.0
• Build package: io.swagger.codegen.v3.generators.php.PhpClientCodegen

Requirements

This library supports the following PHP implementations:

• PHP 8.1
• PHP 8.2
• PHP 8.3
• PHP 8.4

We currently don't support external PHP Runtimes like:

• Bref
• ReactPHP

Installation & Usage

Composer

To install the bindings via Composer, add the following to composer.json:

{
    "require": {
        "fingerprint/fingerprint-pro-server-api-sdk": "dev-main"
    }
}

Then run composer install.

Or you can just run this command on your terminal:

composer require fingerprint/fingerprint-pro-server-api-sdk

Getting Started

Please follow the installation procedure and then run the following:

<?php

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

// Fingerprint Pro Secret API Key
const FPJS_API_SECRET = "Fingerprint Pro Secret API Key";
// A mandatory visitorId of a specific visitor
const FPJS_VISITOR_ID = "visitorId";
// An optional requestId made by a specific visitor
const FPJS_REQUEST_ID = "requestId";

// An optional linkedId of the visit
const FPJS_LINKED_ID = "linkedId";
// An optional parameter limiting scanned results
const LIMIT = 10;
// An optional parameter used to paginate results, see lastTimestamp
const PAGINATION_KEY = "1683900801733.Ogvu1j";

// Import Fingerprint Pro Classes and Guzzle Http Client
use Fingerprint\ServerAPI\Api\FingerprintApi;
use Fingerprint\ServerAPI\Configuration;
use Fingerprint\ServerAPI\Model\EventsUpdateRequest;
use GuzzleHttp\Client;

// Create a new Configuration instance with your Fingerprint Pro Server API Key and your Fingerprint Pro Server API Region.
/**
 * You can specify a region on getDefaultConfiguration function's second parameter
 * If you leave the second parameter empty, then Configuration::REGION_GLOBAL will be used as a default region
 * Options for regions are:
 * Configuration::REGION_EUROPE
 * Congiruration::REGION_GLOBAL
 * Configuration::REGION_ASIA
 */
$config = Configuration::getDefaultConfiguration(FPJS_API_SECRET, Configuration::REGION_EUROPE);
$client = new FingerprintApi(
    new Client(),
    $config
);

// Get an event with a given requestId
try {
    // Fetch the event with a given requestId
    list($model, $response) = $client->getEvent(FPJS_REQUEST_ID);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->getEvent: ', $e->getMessage(), PHP_EOL;
}

// Get a specific visitor's all visits
try {
    // Fetch all visits with a given visitorId, with a page limit
    list($model, $response) = $client->getVisits(FPJS_VISITOR_ID, null, null, LIMIT);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->getVisits: ', $e->getMessage(), PHP_EOL;
}

// Get a specific visitor's all visits with a linkedId
try {
    // Fetch all visits with a given visitorId, with a page limit, skipping the first visit
    list($model, $response) = $client->getVisits(FPJS_VISITOR_ID, null, FPJS_LINKED_ID, LIMIT, PAGINATION_KEY);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->getVisits: ', $e->getMessage(), PHP_EOL;
}

// Use all the parameters on getVisits
try {
    // Fetch the visitor's all visits with a given requestId and linkedId with a page limit while skipping the first visit
    list($model, $response) = $client->getVisits(FPJS_VISITOR_ID, FPJS_REQUEST_ID, FPJS_LINKED_ID, LIMIT, PAGINATION_KEY);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->getVisits: ', $e->getMessage(), PHP_EOL;
}

// Update Event
try {
    $body = new EventsUpdateRequest([
        'linked_id' => 'new linked id',
        'tag' => ['new_property' => 'new value'],
        'suspect' => true,
    ]);
    list($model, $response) = $client->updateEvent($body, FPJS_REQUEST_ID);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->updateEvent: ', $e->getMessage(), PHP_EOL;
}

// Delete by visitor ID
try {
    list($model, $response) = $client->deleteVisitorData(FPJS_VISITOR_ID);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->deleteVisitorData: ', $e->getMessage(), PHP_EOL;
}

⚠️ Warning It's not possible to update events older than 10 days.

⚠️ If you are interested in using deleteVisitorData API, please contact our support team to enable it for you. Otherwise, you will receive a 403.

Sealed results

This SDK provides utility methods for decoding sealed results.

<?php

use Fingerprint\ServerAPI\Sealed\DecryptionAlgorithm;
use Fingerprint\ServerAPI\Sealed\DecryptionKey;
use Fingerprint\ServerAPI\Sealed\Sealed;

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

$sealed_result = base64_decode($_ENV['BASE64_SEALED_RESULT']);
$sealed_key = base64_decode($_ENV['BASE64_KEY']);

try {
    $data = Sealed::unsealEventResponse($sealed_result, [new DecryptionKey($sealed_key, DecryptionAlgorithm::AES_256_GCM)]);

    fwrite(STDOUT, sprintf("Unsealed event: %s \n", $data));
} catch (Exception $e) {
    fwrite(STDERR, sprintf("Exception when unsealing event: %s\n", $e->getMessage()));
    exit(1);
}

To learn more, refer to example located in sealed_results_example.php.

Documentation for API Endpoints

All URIs are relative to your region's base URL.

Region	BasePath
US / Global	https://api.fpjs.io
Europe	https://eu.api.fpjs.io
Asia	https://ap.api.fpjs.io

Webhook Signing

This SDK provides utility method for verifying the HMAC signature of the incoming webhook request. You can use below code to verify signature:

<?php

use Fingerprint\ServerAPI\Webhook\WebhookVerifier;

// Your webhook signing secret.
$webhookSecret = "secret";

// Request data. In real life scenerio this will be the body of incoming request
$webhookData = "data";

// Value of the "fpjs-event-signature" header.
$webhookHeader = "v1=1b2c16b75bd2a870c114153ccda5bcfca63314bc722fa160d690de133ccbb9db";

$isValidWebhookSign = WebhookVerifier::IsValidWebhookSignature($webhookHeader, $webhookData, $webhookSecret);

if(!$isValidWebhookSign) {
    fwrite(STDERR, sprintf("Webhook signature verification failed\n"));
    exit(1);
}

Endpoints

Class	Method	HTTP request	Description
FingerprintApi	deleteVisitorData	DELETE /visitors/{visitor_id}	Delete data by visitor ID
FingerprintApi	getEvent	GET /events/{request_id}	Get event by request ID
FingerprintApi	getVisits	GET /visitors/{visitor_id}	Get visits by visitor ID
FingerprintApi	updateEvent	PUT /events/{request_id}	Update an event with a given request ID

Documentation for Models

• Botd
• BotdBot
• BotdBotResult
• BrowserDetails
• ClonedApp
• DeprecatedGeolocation
• DeveloperTools
• Emulator
• Error
• ErrorCode
• ErrorPlainResponse
• ErrorResponse
• EventsGetResponse
• EventsUpdateRequest
• FactoryReset
• Frida
• Geolocation
• GeolocationCity
• GeolocationContinent
• GeolocationCountry
• GeolocationSubdivision
• GeolocationSubdivisions
• HighActivity
• IPBlocklist
• IPBlocklistDetails
• IPInfo
• IPInfoASN
• IPInfoDataCenter
• IPInfoV4
• IPInfoV6
• Identification
• IdentificationConfidence
• IdentificationSeenAt
• Incognito
• Jailbroken
• LocationSpoofing
• PrivacySettings
• ProductBotd
• ProductClonedApp
• ProductDeveloperTools
• ProductEmulator
• ProductFactoryReset
• ProductFrida
• ProductHighActivity
• ProductIPBlocklist
• ProductIPInfo
• ProductIdentification
• ProductIncognito
• ProductJailbroken
• ProductLocationSpoofing
• ProductPrivacySettings
• ProductProxy
• ProductRawDeviceAttributes
• ProductRemoteControl
• ProductRootApps
• ProductSuspectScore
• ProductTampering
• ProductTor
• ProductVPN
• ProductVelocity
• ProductVirtualMachine
• Products
• Proxy
• RemoteControl
• RootApps
• SuspectScore
• Tampering
• Tor
• VPN
• VPNConfidence
• VPNMethods
• Velocity
• VelocityData
• VelocityIntervals
• VirtualMachine
• Visit
• VisitorsGetResponse
• Webhook
• WebhookClonedApp
• WebhookDeveloperTools
• WebhookEmulator
• WebhookFactoryReset
• WebhookFrida
• WebhookHighActivity
• WebhookIPBlocklist
• WebhookIPInfo
• WebhookJailbroken
• WebhookLocationSpoofing
• WebhookPrivacySettings
• WebhookProxy
• WebhookRemoteControl
• WebhookRootApps
• WebhookSuspectScore
• WebhookTampering
• WebhookTor
• WebhookVPN
• WebhookVelocity
• WebhookVirtualMachine

Documentation for Authorization

ApiKeyHeader

• Type: API key
• API key parameter name: Auth-API-Key
• Location: HTTP header

ApiKeyQuery

• Type: API key
• API key parameter name: api_key
• Location: URL query string

Documentation for sealed results

• Sealed
• DecryptionKey

Documentation for webhooks

• Webhook

Tests

To run the unit tests:

composer install
./vendor/bin/phpunit

Support

To report problems, ask questions or provide feedback, please use Issues. If you need private support, you can email us at [email protected].

License

This project is licensed under the MIT License.