README

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.0.0-rc.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

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->__toString() . "</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.

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

Documentation for Models

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

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 oss-support@fingerprint.com.

License

This project is licensed under the MIT License.

fingerprint / fingerprint-pro-server-api-sdk

Maintainers

Details