README

Fingerprint Server PHP SDK

Fingerprint Server API allows you to get, search, and update 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 OpenAPI Generator project:

• API version: 4
  • Package version: 7.1.0
• Build package: org.openapitools.codegen.languages.PhpClientCodegen

Requirements

This library supports the following PHP implementations:

• 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/server-sdk": "^7.1.0"
    }
}

Then run composer install.

Or you can just run this command on your terminal:

composer require fingerprint/server-sdk

Getting Started

Please follow the installation procedure and then run the following:

<?php

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

// Fingerprint Secret API Key
const FP_API_SECRET = "Fingerprint Secret API Key";
// An optional visitorId of a specific visitor
const FP_VISITOR_ID = "visitorId";
// An optional eventId made by a specific visitor
const FP_EVENT_ID = "requestId";

// An optional linkedId of the visit
const FP_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 Server PHP SDK Classes and Guzzle Http Client
use Fingerprint\ServerSdk\Api\FingerprintApi;
use Fingerprint\ServerSdk\Configuration;
use Fingerprint\ServerSdk\Model\EventUpdate;
use GuzzleHttp\Client;

// Create a new Configuration instance with your Fingerprint Server API Key and your Fingerprint Server API Region.
/**
 * You can specify a region on 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 = new Configuration(FP_API_SECRET, Configuration::REGION_EUROPE);
$client = new FingerprintApi(
    $config,
    new Client(), // This is optional. Default: GuzzleHttp\Client
);

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

// Search for specific events
try {
    // Search events for given visitor id marked as suspicious and "bad" bot
    list($model, $response) = $client->searchEventsWithHttpInfo(LIMIT, visitor_id: FP_VISITOR_ID, bot: SearchEventsBot::BAD, suspect: true);
    // Use pagination key to get the next page
    // list($model, $response) = $client->searchEventsWithHttpInfo(LIMIT, pagination_key: $model->getPaginationKey(), visitor_id: FP_VISITOR_ID, bot: SearchEventsBot::BAD, suspect: true);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->searchEventsWithHttpInfo: ', $e->getMessage(), PHP_EOL;
}

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

// Delete by visitor ID
try {
    list($model, $response) = $client->deleteVisitorDataWithHttpInfo(FP_VISITOR_ID);
    echo "<pre>" . $response->getBody()->getContents() . "</pre>";
} catch (Exception $e) {
    echo 'Exception when calling FingerprintApi->deleteVisitorDataWithHttpInfo: ', $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\ServerSdk\Sealed\DecryptionAlgorithm;
use Fingerprint\ServerSdk\Sealed\DecryptionKey;
use Fingerprint\ServerSdk\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\ServerSdk\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

• BotInfo
• BotResult
• BrowserDetails
• Canvas
• Emoji
• Error
• ErrorCode
• ErrorResponse
• Event
• EventRuleAction
• EventRuleActionAllow
• EventRuleActionBlock
• EventSearch
• EventUpdate
• FontPreferences
• Geolocation
• GeolocationSubdivisionsInner
• IPBlockList
• IPInfo
• IPInfoV4
• IPInfoV6
• Identification
• IdentificationConfidence
• IncrementalIdentificationStatus
• Integration
• IntegrationSubintegration
• PluginsInner
• PluginsInnerMimeTypesInner
• Proximity
• ProxyConfidence
• ProxyDetails
• RareDevicePercentileBucket
• RawDeviceAttributes
• RequestHeaderModifications
• RuleActionHeaderField
• RuleActionType
• SDK
• SearchEventsBot
• SearchEventsIncrementalIdentificationStatus
• SearchEventsRareDevicePercentileBucket
• SearchEventsSdkPlatform
• SearchEventsVpnConfidence
• SupplementaryIDHighRecall
• TamperingConfidence
• TamperingDetails
• TouchSupport
• Velocity
• VelocityData
• VpnConfidence
• VpnMethods
• WebGlBasics
• WebGlExtensions

Documentation for Authorization

bearerAuth

• Type: HTTP basic authentication

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

License

This project is licensed under the MIT License.