Guides
  1. SDK
  2. Web SDK

Alloy SDK Installation

There are 2 ways to integrate with the Alloy SDK:

  • Embedded JavaScript
  • NPM Package

Installation

Embedded JavaScript

Import JavaScript from the Alloy server. On the page where you would like to place the SDK, add Alloy's JavaScript

<script src="https://scripts.alloy.com/2/9/alloy_sdk_bundle.js"></script>

NPM Package

Install the web SDK npm package:

yarn add @alloyidentity/web-sdk

or 

npm install @alloyidentity/web-sdk

Initialization

alloy.init() must be called before any other SDK function. It accepts a configuration object with the parameters below.

  • key — your public SDK key, found in the Alloy dashboard under Settings → SDK.
  • journeyToken — identifies the Journey to run, found under Journeys in the dashboard.

For full parameter details, see Web SDK Functions.

Device and behavioral profiling

Use this initialization when you only need to profile the end user's device or collect behavioral signals.

  • No journeyApplicationToken is required because no document collection step is involved.
  • alloy.init() returns an object that includes alloyRequestFields — a flat map of session tokens collected from active behavioral and fraud detection plugins (e.g., socure_session_id, neuro_user_id, threatmetrix_session_id). 
alloy.init({
  key: "ecfb58b7-a611-4fbd-b727-1b1d2113411a",
  journeyToken:"J-YCMHdHquF111111eM9"
});
📘

Tip

For the most accurate results, initialize profiling as early as practical in the user journey. However, avoid profiling too far in advance of when the profiled session will be sent through Alloy to the third-party data provider for evaluation, as long delays may reduce the effectiveness of the collected signals.


Document collection

Use this initialization when the Journey includes document verification.

  • journeyApplicationToken is required to associate the SDK session with a specific application.
  • Set skipBehavioralPluginsFetch: true if no behavioral plugins are configured — this skips an unnecessary API call and reduces latency.
alloy.init({
  key: "ecfb58b7-a611-4fbd-b727-1b1d2113411a",
  production: true,
  skipBehavioralPluginsFetch: true,
  journeyApplicationToken: "JA-hlZa11yUJYkTNzUTl116",
  journeyToken:"J-YCMHdHquF111111eM9"
});
📘

For non-US regions and specific Alloy tenants, please refer to instructions here to pass in additional parameters.

Embedded JavaScript Example

<!DOCTYPE html>
<html>
  <head>
    <title>Alloy SDK Example Vanilla</title>
    <script src="https://scripts.alloy.com/2/9/alloy_sdk_bundle.js"></script>
    <!-- charset and viewport meta tags are required! -->
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>

  <script>
    // Declare your SDK parameters
    const alloyInitParams = {
      key: "xyz",
      journeyToken: "J-XYZ",
      journeyApplicationToken: "JA-XYZ"
    };

    const onClick = async () => {
      // Init SDK
      const init = await alloy.init(alloyInitParams);
      // If using Iovation or NeuroID, you can retrieve the needed fields from the returned object, when using Alloy's init function
      console.log("init-->", init);
      // This is a sample callback function. This function can be passed into the open function, and will be exectuted when the SDK closes
      const callback = (data) => {
        console.log(data);
      };

      // Open the SDK. The "open" function allows the use of an optional parameter to mount the alloy modal inside a div identified by its ID or class name.
      // If not specified, it'll be absolute positioned in the middle of the document.
      alloy.open(callback, "renderComponent");
    };
  </script>
  <body>
    <div className="App">
      <div className="buttonContainer">
        <button onclick="onClick()">Run SDK</button>
      </div>
      <div id="renderComponent"></div>
    </div>
  </body>
</html>

NPM Package Example

import React from 'react';
import alloy from '@alloyidentity/web-sdk';
import './App.css';

// Declare your SDK parameters
const alloyInitParams = {
  key: 'xyz',
  journeyApplicationToken: 'JA-xyz',
  journeyToken: 'J-XYZ'
};
// Initialize the Alloy SDK
alloy.init(alloyInitParams);

function App() {
  //  // This is a sample callback function. This function can be passed into the open function, and will be exectuted when the SDK closes
  const callback = data => {
    console.log(data);
  };

  const onOpen = () => {
    const anchorElementSelected = document.getElementById('anchors');
    const anchorElement =
      anchorElementSelected.options[anchorElementSelected.selectedIndex].value;
    // Open the SDK. The "open" function allows the use of an optional parameter to mount the alloy modal inside a div identified by its ID or class name.
    // If not specified, it'll be absolute positioned in the middle of the document.
    alloy.open(callback, anchorElement);
  };

  const onClose = () => {
    alloy.close();
  };

  return (
    <>
      <div className="App">
          <div className="buttonContainer">
            <select name="anchors" id="anchors">
              <option value={undefined}>No anchor</option>
              <option value="anchorElementContainer1">Left anchor</option>
              <option value="anchorElementContainer2">Right anchor</option>
              <option value="anchorElementContainer3">Bottom anchor</option>
            </select>
            <button onClick={onOpen}>Open</button>
            <button onClick={onClose}>Close</button>
          </div>
          <div className="anchorContainer">
            <div className="anchorElementContainer1">(ID: anchor1)</div>
            <div className="anchorElementContainer2">(className: anchor2)</div>
            <div className="anchorElementContainer3">(className: anchor3)</div>
          </div>
        </div>
    </>
  );
}

export default App;

Updated 14 days ago

What’s Next

Starting and Using the SDK

Did this page help you?