Guides
Sign Up

Fastly Compute Proxy Integration Open Response Plugins

Process identification results directly in your Fastly Compute proxy integration

Suggest Edits

Enabling Open client response for your Fingerprint workspace lets you process the full device intelligence result directly in your Fastly Compute proxy integration. This approach can reduce latency and increase the security of the Fingerprint implementation because you can avoid passing the result from your proxy to your client and then from your client to the server.

You can process device intelligence results in your Fastly Compute proxy integration using plugins inside the integration's Compute package. The integration includes an example plugin that stores every identification result in your Fastly KV Store.

In this guide you will learn how to:

📘

Before you start

  • This guide assumes you already have already deployed your Fastly Compute proxy integration.
  • This guide assumes have read the Open client response documentation and enabled open client response for your Fingerprint application. This is an advanced configuration option limited to Enterprise customers. Get in touch with our support team if you have any questions.

🚧

Missing mobile SDKs support

Open client response is only suppported in the Fingerprint JavaScript agent. The iOS and Android SDKs currently do not support open client response.

Enable plugins in your proxy integration

Follow these steps to enable the plugin system in your integration. This is necessary for both the example KV Store plugin and your custom plugins.

Step 1: Enable plugins in your Fingerprint Config store

This step assumes you have already contacted the Fingerprint support team and enabled Open client response for your Fingerprint workspace. That means your Fastly proxy integration already receives deobfuscated device intelligence results from Fingerprint.

To start processing those results with plugins, you need to enable them explicitly:

  1. Inside your Fastly dashboard, navigate to Resources > Config stores > Fingerprint_Compute_Config_Store_<SERVICE_ID>.
  2. Create an item OPEN_CLIENT_RESPONSE_PLUGINS_ENABLED and set it to true. The integration will process the open client response and run all registered plugins. You can set this flag to false to disable all plugins at once.

Step 2: Add a decryption key to your Secret store

To decrypt the response coming from the Fingerprint API to your proxy integration, plugins need to access your Fingerprint workspace's decryption key. Store the decryption key in your proxy integration's Secret store:

  1. Inside your Fastly dashboard, navigate to Resources > Secret stores > Fingerprint_Compute_Secret_Store_<SERVICE_ID>.
  2. Create an item DECRYPTION_KEY and set it to the value of your decryption key.

Use the example KV Store plugin

The example plugin provided with the integration decrypts the Fingerprint result and saves it to a Fastly KV Store. Assuming you have already enabled plugins in your integration, follow these steps to start using the KV store plugin:

Step 1: Create a KV Store

Plugins run on the edge and can access Fastly resources like KV Stores, Secret stores, and Config stores. To use the example plugin to store Fingerprint results on the edge, create a KV Store:

  1. Inside the Fastly dashboard, navigate to Resources > KV Stores.
  2. Click Create a KV Store.
  3. Name it Fingerprint_Results_<SERVICE_ID> where the suffix is your proxy integration's Compute Service ID. Make sure you have no spaces in the KV store name after copy-pasting your service ID.
  4. Click Add.
  5. In your KV store, click Link to services.
  6. Select your proxy integration service, click Link and activate, and Confirm and activate.
  7. Click Finish.

Step 2: Enable the KV Store plugin

  1. Inside your Fastly dashboard, navigate to Resources > Config stores > Fingerprint_Compute_Config_Store_<SERVICE_ID>.
  2. Create an item SAVE_TO_KV_STORE_PLUGIN_ENABLED and set it to true. This specifically enables only the example KV Store plugin. You can set this flag to false to disable only this plugin.

Step 3: Test the KV Store plugin

To test the plugin:

  1. Use the Fingerprint client agent to make identification requests through your Fastly Compute proxy integration.
  2. After a few moments, you should see the results of these identification events inside your KV Store.

If you don't see the results:

  • Go to your integration's status page at metric.yourwebsite.com/status to see that your integration is working and all required variables are set.
  • Double-check the names of your Config store, Secret store, and KV Store. Check the names and values of all the configuration variables.
  • Examine the logs of your proxy integration for errors.
  • Contact our support team.

📘

Note: Error handling and latency

The proxy integration runs the plugins after it sends the identification response to the client. Plugins cannot interfere with or delay proxying requests, even if they fail. The integration logs and ignores any errors thrown by the plugin.

Make your own plugin

You can use the example KV Store plugin described above as a reference to create and deploy your own plugins. Assuming you have already enabled plugins in your integration, follow the steps below:

Step 1: Fork the integration repository

When first installing the Fastly Compute proxy integration, you have likely deployed the default service package from the GitHub releases. To include a custom plugin with the proxy service package, you need to build your own version of the package instead:

  1. Fork the Fastly Compute proxy integration repository to your own GitHub account. This allows you to manage and deploy your custom plugins while staying in sync with the base repository.

  2. Clone the forked repository to your local machine: 

    git clone https://github.com/YOUR_GITHUB_USERNAME/fingerprint-pro-fastly-compute-proxy-integration.git
cd fingerprint-pro-fastly-compute-proxy-integration

  3. Install dependencies using PNPM: 

    pnpm install

Step 2: Implement your custom plugin

Implement your plugin inside the plugins folder: 

// plugins/yourPlugin.ts
import { getConfigStore } from '../src/utils/getStore' 
import { ProcessOpenClientResponseContext } from '../src/utils/registerPlugin'

export async function yourPlugin(context: ProcessOpenClientResponseContext) {
  // Optional 'enabled' check
  const configStore = getConfigStore()
  const isPluginEnabled = configStore?.get('YOUR_PLUGIN_ENABLED') === 'true'
  if (!isPluginEnabled) {
    return
  }
  // Process the result as you need
  console.log(context.event, context.httpResponse);
}
  • A plugin is a callback function that receives ProcessOpenClientResponseContext as its argument. The response context includes the Fingerprint identification event with the complete device intelligence result.
  • You can use a custom item in your integration's Config store to enable or disable the plugin. If you implement this check, do not forget to add the item to your Config store.
  • See the example saveToKVStore.ts plugin for reference.
  • See processOpenClientResponse.ts to see how the callback is called.

Step 3: Register the plugin

Register your plugin inside the plugins/index.ts file:

import { saveFingerprintResultToKVStore } from './saveToKVStore'
+ import { yourPlugin } from './yourPlugin'
import { Plugin } from '../src/utils/registerPlugin'

export default [
  {
    name: 'Save Fingerprint Result to KV Store',  
    callback: saveFingerprintResultToKVStore,
    type: 'processOpenClientResponse',
  },
+ {
+   name: 'Your plugin',
+   callback: yourPlugin,
+   type: 'processOpenClientResponse',
+ },
] satisfies Plugin[]

Step 4: Compile your custom package

Compile the package by running: 

fastly compute build

The resulting pkg/fingerprint-fastly-compute-proxy-integration.tar.gz package file now includes your plugin.

Note: You can confirm this by searching for your package name in build/index.js.

Step 5: Deploy your custom package

You have two options for deploying your custom package in your proxy integration Compute service — using the Fastly UI or the Fastly CLI.

Using Fastly UI

  1. Go to Fastly Dashboard.
  2. Open your proxy integration Compute Service and click Edit configuration > Clone version (active) to edit.
  3. Click Package in the left-hand menu.
  4. Click Upload new package and upload the fingerprint-fastly-compute-proxy-integration.tar.gz file.
  5. Click Activate in the top right to deploy a new version of your service.

Using Fastly CLI

  1. Install the Fastly CLI on your local machine for managing deployments.

    fastly profile create

  2. Inside your fork of the proxy integration Git repository, update the fastly.toml file to include your details:

    • Update service_id to the service ID of your proxy integration’s Compute service.
    • Update authors to add your name and email address.
    • Update description to provide a custom description for your service.
    # This file describes a Fastly Compute package. To learn more visit:
# https://developer.fastly.com/reference/fastly-toml/

authors = ["YOUR_EMAIL"]
cloned_from = "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration"
description = "Fingerprint Proxy Fastly Compute Package"
language = "javascript"
manifest_version = 3
name = "fingerprint-fastly-compute-proxy-integration"
service_id = "YOUR_SERVICE_ID"

[scripts]
  build = "pnpm build"
  post_init = "pnpm install"

  3. Deploy your custom proxy service package to your proxy integration’s Fastly Compute service: 

    fastly compute publish

Step 6: Test your plugin

  1. Verify the deployment status of your service in the Fastly dashboard.
  2. Check that the plugin behaves as you expect.
  3. If necessary, examine your integration's service logs.

Note: The proxy integration runs the plugins after it sends the identification response to the client. Plugins cannot interfere with or delay proxying requests, even if they fail. The integration logs and ignores any errors thrown by the plugin.

If you encounter any problems, you can get in touch with our support team.

Step 7: Keep your forked repository up to date

Keep your fork up to date by regularly pulling and merging updates from the main repository:

git remote add upstream https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration
git fetch upstream
git merge upstream/main

Minor version updates from the main repository will not disrupt your custom plugins as long as you stick to the plugin API contract described above.

Updated 7 days ago