Getting started overview

Integrating FingerprintJS Pro involves a sequence of steps designed to enable device identification within your application. The process typically begins with account creation, followed by obtaining the necessary API keys. Subsequently, developers integrate a client-side SDK or the CDN into their front-end application to collect visitor data and generate unique identifiers. For server-side validation or additional data processing, the Server API can be utilized. The core output is a stable, unique identifier for each visitor, even when cookies are cleared or incognito mode is used, which assists in use cases such as fraud detection and personalized user experiences.

The following table outlines the key steps to get started with FingerprintJS Pro:

Step What to do Where
1. Sign Up Create a FingerprintJS Pro account. FingerprintJS Pro Login Page
2. Get API Keys Locate your Public API Key and Secret API Key. FingerprintJS Pro API Keys documentation
3. Choose Integration Method Select a client-side SDK (JavaScript, React Native, etc.) or CDN. FingerprintJS Pro documentation
4. Install SDK/CDN Add the chosen library to your project. FingerprintJS Pro documentation
5. Make First Request Initialize the client and request a visitor identifier. Your application's frontend code
6. Verify Results Check the API response for the visitor ID and additional data. Your application's console or server logs

Create an account and get keys

To begin using FingerprintJS Pro, you must first create an account. This process typically involves providing an email address and setting a password. Upon successful registration, you will gain access to the FingerprintJS Pro dashboard, which serves as the central hub for managing your projects, viewing analytics, and accessing your API keys.

API keys are fundamental for authenticating your requests to the FingerprintJS Pro API. FingerprintJS Pro utilizes two primary types of API keys:

  • Public API Key: This key is used on the client side (e.g., in your JavaScript code) to initialize the FingerprintJS Pro agent and make requests for visitor identification. It is designed to be public and can be exposed in your frontend code.
  • Secret API Key: This key is used for server-side operations, such as calling the FingerprintJS Pro Server API to retrieve detailed visitor history or to validate client-side identification requests. The Secret API Key must be kept confidential and should never be exposed in client-side code.

You can locate your API keys within the FingerprintJS Pro dashboard. Navigate to the "API Keys" or "Settings" section, where both your Public and Secret API Keys will be displayed. It is recommended to copy these keys and store them securely, especially the Secret API Key, for use in your application's configuration.

Your first request

The following example demonstrates how to integrate the FingerprintJS Pro JavaScript SDK and make your first identification request. This example uses the CDN integration method for simplicity, which is suitable for quick testing and certain production environments. For more advanced setups or specific frameworks, consult the FingerprintJS Pro documentation.

First, include the FingerprintJS Pro CDN script in the <head> of your HTML file:

<script
  async
  src="//cdn.jsdelivr.net/npm/@fingerprintjs/fingerprintjs-pro@3/dist/fp.min.js"
></script>

Next, add JavaScript code to initialize the agent and request a visitor identifier. Replace YOUR_PUBLIC_API_KEY with your actual Public API Key obtained from the FingerprintJS Pro dashboard:

(async () => {
  // Initialize the agent with your Public API key
  const fpPromise = import('//cdn.jsdelivr.net/npm/@fingerprintjs/fingerprintjs-pro@3')
    .then(FingerprintJS => FingerprintJS.load({
      apiKey: 'YOUR_PUBLIC_API_KEY'
    }));

  // Get the visitor identifier when the agent is ready
  fpPromise
    .then(fp => fp.get())
    .then(result => {
      // This is the visitor identifier:
      const visitorId = result.visitorId;
      console.log("Visitor ID:", visitorId);

      // Log the full result object for inspection
      console.log("Full FingerprintJS Pro result:", result);

      // Example: Display visitor ID on the page
      const outputElement = document.getElementById('visitorIdOutput');
      if (outputElement) {
        outputElement.textContent = `Visitor ID: ${visitorId}`;
      }
    })
    .catch(error => {
      console.error("FingerprintJS Pro error:", error);
    });
})();

To display the visitor ID on your page, add an HTML element with the ID visitorIdOutput:

<p id="visitorIdOutput">Loading visitor ID...</p>

When this code executes in a web browser, the FingerprintJS Pro agent will collect various browser and device signals to generate a unique visitorId. This ID is then logged to the console and displayed on the webpage.

Common next steps

After successfully obtaining your first visitor identifier, several common next steps can enhance your integration with FingerprintJS Pro:

  • Server-Side Verification: For critical operations like fraud detection, it is recommended to send the client-side generated visitorId to your backend server. Your server can then use the FingerprintJS Pro Server API with your Secret API Key to retrieve detailed event data and verify the client-side identification request. This adds a layer of security and ensures that the identification data has not been tampered with.
  • Customizing Identification: FingerprintJS Pro allows for customization of the identification process by passing additional data or tags with your requests. This can include user IDs, transaction IDs, or other relevant metadata that can help enrich the identification context in your FingerprintJS Pro dashboard and analytics. Refer to the JavaScript Agent API documentation for options.
  • Integrating Webhooks: To receive real-time notifications about new visitor identifications or specific events, you can configure webhooks. Webhooks allow FingerprintJS Pro to send automated HTTP POST requests to a specified URL on your server whenever an event occurs, enabling immediate processing of identification data without constant polling. Twilio's webhook security guide provides general best practices for securing webhook endpoints.
  • Bot Detection Integration: If bot detection is a primary concern, explore integrating Fingerprint BotD. This separate product from FingerprintJS Pro is specifically designed to identify and mitigate automated bot traffic, complementing the core device identification capabilities.
  • Dashboard and Analytics: Regularly review the FingerprintJS Pro dashboard. It provides insights into your traffic, identification accuracy, and potential fraud patterns. Understanding these analytics can help you refine your fraud prevention strategies and optimize your application.
  • Error Handling and Monitoring: Implement robust error handling for your FingerprintJS Pro integration. Monitor API call successes and failures, and set up alerts for any anomalies. This ensures the reliability of your identification process and allows for quick resolution of issues.

Troubleshooting the first call

When making your first call to FingerprintJS Pro, you might encounter issues. Here are common problems and their potential solutions:

  • Incorrect API Key:
    • Symptom: The agent fails to initialize, or you receive authentication errors.
    • Solution: Double-check that you are using the correct Public API Key for client-side integration. Ensure there are no typos or extraneous spaces. Verify the key in your FingerprintJS Pro dashboard.
  • Network Issues or Ad Blockers:
    • Symptom: The script fails to load, or the API call never completes.
    • Solution: Check your browser's developer console for network errors. Ad blockers or privacy extensions can sometimes interfere with third-party scripts. Try disabling them temporarily or testing in an incognito window without extensions. Ensure your network allows connections to cdn.jsdelivr.net and api.fingerprint.com.
  • CORS Policy Errors:
    • Symptom: "Access-Control-Allow-Origin" errors in the browser console.
    • Solution: While less common with standard FingerprintJS Pro CDN integration, ensure your application's domain is correctly configured if you are using a custom endpoint or proxy. The MDN Web Docs on CORS provide background on Cross-Origin Resource Sharing.
  • Asynchronous Script Loading:
    • Symptom: JavaScript errors indicating FingerprintJS is not defined or similar.
    • Solution: Ensure your JavaScript code that initializes FingerprintJS Pro runs only after the CDN script has fully loaded. The provided example uses async on the script tag and a promise-based approach (.then(FingerprintJS => FingerprintJS.load(...))) to handle this correctly. Avoid executing initialization code directly in the global scope without waiting for the script.
  • Rate Limiting:
    • Symptom: Requests start failing after a certain number of successful calls, often with HTTP 429 status codes.
    • Solution: Check your FingerprintJS Pro plan limits. The free tier includes 50,000 requests per month. If you exceed this, you may need to upgrade your plan. The FingerprintJS Pro pricing page details available tiers.
  • Outdated SDK Version:
    • Symptom: Unexpected behavior or errors that are not well-documented.
    • Solution: Ensure you are using a recent version of the FingerprintJS Pro SDK. The CDN URL in the example points to @3, indicating the major version. Check the FingerprintJS Pro release notes for any breaking changes or required updates.