Innerworks Fraud Detection Suite SDK

Communication with innerworks API requires the configuration of a project with a project ID and secret. Currently the product is still in early private beta, contact us via our website at innerworks.me for assistance with setup and to receive your project credentials.

For a full interactive example of how to install and use the SDK, please visit this repo

Installation

We host our SDK through npm, so to install it for your project simply run the following in the command line

npm i @innerworks-me/iw-auth-sdk --save

Innerworks Fraud Detection with Authentication - React Integration

Our flagship product is a wrapper over Google Sign-On with invisible fraud detection acting in the background.

Setup

First import the SDK and necessary react hooks

import { InnerworksAuth } from "@innerworks-me/iw-auth-sdk";
import { useEffect, useRef, useState } from 'react';

Then initialize it

const [innerworksAuth, setInnerworksAuth] = useState<InnerworksAuth | null>(null);

useEffect(() => {
    setInnerworksAuth(new InnerworksAuth("{your project id}", "{your redirect url}"));
}, [setInnerworksAuth]);

Render Button

You can use the useRef hook to allow the innerworks SDK to create a dynamically render a signIn button

"use client"

import { useEffect, useRef, useState } from 'react';
import { InnerworksAuth } from "@innerworks-me/iw-auth-sdk";

export default function FrontendFlowDemoPage() {

    const [innerworksAuth, setInnerworksAuth] = useState<InnerworksAuth | null>(null);
    const buttonContainerRef = useRef<HTMLDivElement>(null);

    useEffect(() => {
        setInnerworksAuth(new InnerworksAuth("{your project id}", "{your redirect url}"));
    }, [setInnerworksAuth]);

    useEffect(() => {
        if(innerworksAuth && buttonContainerRef.current) {
            // Generate the button and append it to the buttonContainerRef
            const button = innerworksAuth.getInnerworksSignInButton();
            buttonContainerRef.current.appendChild(button);
        }
    }, [innerworksAuth]);
    
    return (
        <div id="sign-in-button" ref={buttonContainerRef}/></div>
    );
}

Handling Redirects

This will redirect the user to a sign-on page, prompt for their authentication, and finally redirect to the page you specified. Depending on the success of the authentication the URL parameters will either contain an id or error field. These will need to be parsed depending on your framework and whether your redirect page is server or client side, for example - here's how we do it in NextJS

"use client"

import { useSearchParams } from 'next/navigation';

export default function Callback() {
  const searchParams = useSearchParams();
  const params = Object.fromEntries(searchParams);
  const error = params.error;
  const id = params.id;

  return (
    <Layout>
      <div>
        {!id && (
          <div>
            Error: {error ?? "An error has occurred on our end..."}
          </div>
        )}
        {id && !error && (
          <div>
            Authentication Successful!
          </div>
        )}
      </div>
    </Layout>
  );
}

Innerworks Fraud Detection (No Authentication) - React Integration

If you prefer to retain your existing authentication provider, or you do not wish to protect a login but something else instead (maybe an email sign up for example), the Innerworks Fraud Detection Suite can be installed and sit invisibly in the background to perform bot detection and user coherence for your use case.

Setup

First, in your frontend page, import the InnerworksMetrics object to collect metrics.

import { InnerworksMetrics } from "@innerworks/iw-auth-sdk";

Initialise the InnerworksMetrics object in your page as follows

const [innerworksMetrics, setInnerworksMetrics] = useState<InnerworksMetrics>();

useEffect(() => {
    setInnerworksMetrics(new InnerworksMetrics(<yourAppID>));
}, [setInnnerworksMetrics]);

recommended: if you want to collect button UI metrics, pass a css selector to collect metrics on the already exiting button that is meant to trigger Innerworksʼ fraud detection (css selector accepted are ID, Class, Tag, Attribute, pseudo-class, etc).

const [innerworksMetrics, setInnerworksMetrics] = useState<InnerworksMetrics>();

useEffect(() => {
    setInnerworksMetrics(new InnerworksMetrics(<yourAppID>, #signin-button));
}, [setInnnerworksMetrics]);

Send Metrics On Submission

In the webpage, where the user submits a form, signs in or submits a tx, call send(<unique-id>) on the innerworksMetrics object, passing a unique identifier for the user (i.e. email, username or wallet address). This returns a boolean indicating the success of the request - which you can optionally use.

i.e:

const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
	e.preventDefault();

	/*
	handle form submission here e.g. authentication
	*/
	
	if (innerworksMetrics) { // necessary if using typescript
		const metricsSendSuccess = await innerworksMetrics.send(<unique-id>);
	}
	// optionally handle based on metricsSendSuccess
}

Full Integration

Overall the integration code would look like:

import { InnerworksMetrics } from "@innerworks-me/iw-auth-sdk";
import { useEffect } from "react";

export default function YourPage() {
	const [innerworksMetrics, setInnerworksMetrics] = useState<InnerworksMetrics>();
	
	useEffect(() => {
		setInnerworksMetrics(new InnerworksMetrics(<yourAppId>, "#signin-button"));
	}, [setInnerworksMetrics]);
	
	const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
		e.preventDefault();
	
		/*
		handle form submission here e.g. authentication
		*/
		
		if (innerworksMetrics) { // necessary if using typescript
			const metricsSendSuccess = await innerworksMetrics.send(<unique-id>);
		}
		// optionally handle based on metricsSendSuccess
	}
	
	return (
		// ... rest of elements
        	<form onSubmit={handleSubmit}>

			/* ...
			your form elements here
			... */

			<button type="submit" id="signin-button">
		</form>
	)
}