Login with DIMO

Login with DIMO is a React component SDK, providing developers with a set of pre-built, customizable building blocks for applications that integrate with DIMO. These components simplify the process of integrating Accounts API and Transactions SDK in React applications.

Installation

To install the SDK, use npm or yarn to add the package to your project:

npm i @dimo-network/login-with-dimo

or

yarn add @dimo-network/login-with-dimo

Usage

You can integrate the LoginWithDimo component into your React application to allow users to authenticate with Dimo. The component handles the authentication process in a popup window and triggers the appropriate callback functions upon success or error.

Initialize DIMO SDK

import {
  initializeDimoSDK,
} from "@dimo-network/login-with-dimo";

  initializeDimoSDK({
    clientId: "YOUR_CLIENT_ID",
    redirectUri: "YOUR_REDIRECT_URI",
    apiKey: "YOUR_API_KEY",
    environment: "development" | "production",
  });

In addition to setting the dev credentials/environments, you can also set global options.

We currently support the forceEmail option, which means - anytime a user will be on a register/login page, they will be forced to check the email box before registering

  initializeDimoSDK({
    ...
    options: {
      forceEmail: true, //BY DEFAULT, this is False - users won't have to share email
    },
  });

The Dimo Auth Provider

The Dimo Auth Provider is used to get values of an authenticated state from the SDK. This includes, a boolean "authenticated" property, a method to get the currently valid JWT, an email property, a method to get email, and the wallet address

Any components that require this value should be wrapped in the DimoAuthProvider, as follows

<DimoAuthProvider>
    <SomeComponentThatNeedsDimoState/>
</DimoAuthProvider/>

Now, in the component the auth state can be fetched as follows

import {,
  useDimoAuthState,
} from "@dimo-network/login-with-dimo";

const { isAuthenticated, getValidJWT, getEmail, email, walletAddress } = useDimoAuthState();

Based on this authenticated state, you can render the necessary Dimo components

The Separate DIMO Modes

With the DIMO SDK, developers have the ability to control how their users interact with DIMO.

We offer two options

• Popup Mode (best for allowing users to see both the app, as well as DIMO)
• Redirect Mode (best for developers that want to avoid popups)

Using the Button Components

The following example shows all buttons being rendered, with no auth state checking

import {
  LoginWithDimo,
  ShareVehiclesWithDimo,
  ExecuteAdvancedTransactionWithDimo,
} from "@dimo-network/login-with-dimo";

<LoginWithDimo
  mode="popup"
  onSuccess={(authData) => console.log("Success:", authData)}
  onError={(error) => console.error("Error:", error)}
  permissionTemplateId={permissionsEnabled ? "1" : undefined} //This will control if your users are asked to share vehicles, as part of the login flow. "1" is the template for all SACD permissions
  utm="utm_campaign=dimo"
  // Optionally, specify vehicles/onboarding oracles (uncomment the line below to use it)
  // vehicles={["585","586"]}  // Specify the vehicles to be accessed after login
  // onboarding={["tesla"]}  // Specify the vehicles to be accessed after login
  />

<ShareVehiclesWithDimo
  mode="popup"
  onSuccess={(authData) => console.log("Success:", authData)} //authData will include the sharedVehicles
  onError={(error) => console.error("Error:", error)}
  permissionTemplateId={"1"} //REQUIRED: "1" is the template for all SACD permissions
  // expirationDate={} // Optional ISO string
  // Optionally, specify vehicles/onboarding oracles (uncomment the line below to use it)
  // vehicles={["585","586"]}  // Specify the vehicles to be accessed when triggered
  // onboarding={["tesla"]}  // Specify the vehicles to be accessed after login
  />

<ExecuteAdvancedTransactionWithDimo
  mode="popup"
  onSuccess={(transactionData: any) =>
    console.log("Success:", transactionHash)
  }
  onError={(error: any) => console.error("Error:", error)}
  address="0x21cFE003997fB7c2B3cfe5cf71e7833B7B2eCe10"
  value="0"
  abi={sampleAbi} //Some sample ABI required
  functionName="transfer"
  args={["0x62b98e019e0d3e4A1Ad8C786202e09017Bd995e1", "0"]}
/>

Putting it all together

In many cases - developers may want to couple/decouple usage of these components

A common flow is

1. Show the login button, when in authenticated
2. Show the Share Vehicles and Execute Advanced Transaction button, when authenticated

This can be achieved by simply wrapping those buttons in a conditional as follows, to create a full example as follows

import {
  LoginWithDimo,
  ShareVehiclesWithDimo,
  ExecuteAdvancedTransactionWithDimo,
  initializeDimoSDK,
  useDimoAuthState,
} from "@dimo-network/login-with-dimo";

const { isAuthenticated, getValidJWT, email, walletAddress, getEmail } = useDimoAuthState();

useEffect(()=>{
  if ( isAuthenticated ) {
    //makeAuthenticatedRequest(getValidJWT())
    console.log(email);
    console.log(walletAddress);
  }
},[isAuthenticated])

initializeDimoSDK({
  clientId: process.env.REACT_APP_DIMO_CLIENT_ID!,
  redirectUri: process.env.REACT_APP_DIMO_REDIRECT_URI!,
});

...


{isAuthenticated ? (
  <ShareVehiclesWithDimo
    mode="popup"
    onSuccess={(authData) => console.log("Success:", authData)}
    onError={(error) => console.error("Error:", error)}
    permissionTemplateId={"1"}
    // expirationDate={} // Optional ISO string
  />

  <ExecuteAdvancedTransactionWithDimo
    mode="popup"
    onSuccess={(transactionData: any) =>
      console.log("Transaction Hash:", transactionData.transactionHash)
    }
    onError={(error: any) => console.error("Error:", error)}
    address="0x21cFE003997fB7c2B3cfe5cf71e7833B7B2eCe10"
    value="0"
    abi={sampleAbi}
    functionName="transfer"
    args={["0x62b98e019e0d3e4A1Ad8C786202e09017Bd995e1", "0"]}
  />
) : (
  <LoginWithDimo
    mode="popup"
    onSuccess={(authData) => console.log("Success:", authData)}
    onError={(error) => console.error("Error:", error)}
    permissionTemplateId={permissionsEnabled ? "1" : undefined}
    // expirationDate={} // Optional ISO string
    // vehicles={["585","586"]}
  />
)}

Component Descriptions and Parameters

LoginWithDimo

The LoginWithDimo component allows users to authenticate with DIMO.

| Parameter | Description | Default Value | Type | Mandatory | |------------------------|----------------------------------------------|------------------------------|--------------------------------|-----------| | mode | Mode of the button (popup, redirect) | N/A | "popup" \| "redirect" | Yes | | onSuccess | Callback function to handle success | N/A | (authData: AuthData) => void | Yes | | onError | Callback function to handle errors | N/A | (error: Error) => void | Yes | | permissionTemplateId | Permissions template ID | undefined | string | No | | vehicles | List of vehicles | undefined | string[] | No | | vehicleMakes | List of vehicle makes | undefined | string[] | No | | powertrainTypes | List of vehicle powertrain types | undefined | string[] | No | | onboarding | List of oracles for onboarding | undefined | string[] | No | | expirationDate | Expiration date for permissions | undefined | string | No | | authenticatedLabel | Label when the user is authenticated | "Manage DIMO Account" | string | No | | unAuthenticatedLabel | Label when the user is not authenticated | "Continue with DIMO" | string | No | | utm | UTM parameters for tracking (a query string) | null | string | No | | altTitle | Alternative title for the button | false | boolean | No |

ShareVehiclesWithDimo

The ShareVehiclesWithDimo component allows users to share their vehicles data with DIMO.

| Parameter | Description | Default Value | Type | Mandatory | |-----------------------|-----------------------------------------------------------------------------|-----------------------------------------|--------------------------------|-----------| | mode | Mode of the button (popup, redirect) | N/A | "popup" \| "redirect" | Yes | | onSuccess | Callback function to handle success | N/A | (authData: AuthData) => void | Yes | | onError | Callback function to handle errors | N/A | (error: Error) => void | Yes | | permissionTemplateId| Permissions template ID | N/A | string | Yes | | permissions | Array of permission strings to request specific access (see below) | undefined | string[] | No | | vehicles | List of vehicles | undefined | string[] | No | | vehicleMakes | List of vehicle makes | undefined | string[] | No | | powertrainTypes | List of vehicle powertrain types | undefined | string[] | No | | onboarding | List of oracles for onboarding | undefined | string[] | No | | expirationDate | Expiration date for permissions | undefined | string | No | | authenticatedLabel | Label when the user is authenticated | "Share Vehicles with DIMO" | string | No | | unAuthenticatedLabel| Label when the user is not authenticated | "Sign in to Share Vehicles with DIMO" | string | No | | utm | UTM parameters for tracking (a query string) | null | string | No | | altTitle | Alternative title for the button | false | boolean | No |

Available Permissions

When using the permissions prop, you can include either string literals or use the Permissions enum for better type safety. The available permissions are:

• NONLOCATION_TELEMETRY: Access to non-location vehicle telemetry
• COMMANDS: Execute vehicle commands
• CURRENT_LOCATION: Access to current vehicle location
• ALLTIME_LOCATION: Access to historical location data
• CREDENTIALS: Access to VIN credentials
• STREAMS: Access to live data streams
• RAW_DATA: Access to raw vehicle data
• APPROXIMATE_LOCATION: Access to approximate location data

Example Usage:

Using string literals:

<ShareVehiclesWithDimo
  permissions={[
    'NONLOCATION_TELEMETRY',
    'CURRENT_LOCATION',
    'STREAMS'
  ]}
  // other props...
/>

Using the Permissions enum (recommended for TypeScript projects):

import { Permissions } from '@dimo-network/login-with-dimo';

// ...

<ShareVehiclesWithDimo
  permissions={[
    Permissions.GetNonLocationHistory,
    Permissions.GetCurrentLocation,
    Permissions.GetLocationHistory,
    Permissions.GetVINCredential,
    Permissions.GetLiveData
  ]}
  // other props...
/>

ExecuteAdvancedTransactionWithDimo

The ExecuteAdvancedTransactionWithDimo component allows users to execute advanced web3 transactions with DIMO.

| Parameter | Description | Default Value | Type | Mandatory | |-----------------------|-----------------------------------------------------------------------------|----------------------------------------------|----------------------------------|-----------| | mode | Mode of the button (popup, redirect) | N/A | "popup" \| "redirect" | Yes | | onSuccess | Callback function to handle success | N/A | (transactionData: any) => void | Yes | | onError | Callback function to handle errors | N/A | (error: Error) => void | Yes | | address | Address for the transaction | N/A | string | Yes | | value | Value for the transaction | "" | string | No | | abi | ABI for the transaction | N/A | any | Yes | | functionName | Function name for the transaction | N/A | string | Yes | | args | Arguments for the transaction | N/A | string[] | Yes | | authenticatedLabel | Label when the user is authenticated | "Execute Advanced Transaction with Dimo" | string | No | | unAuthenticatedLabel| Label when the user is not authenticated | "Sign in to Execute Transaction" | string | No | | altTitle | Alternative title for the button | false | boolean | No |

LogoutWithDimo

The LogoutWithDimo component allows users to log out of their DIMO session. It clears the session data, including cookies and local storage, and updates the authentication state.

Example Usage

import { LogoutWithDimo } from "@dimo-network/login-with-dimo";

<LogoutWithDimo
  mode="popup" // or "redirect"
  onSuccess={() => console.log('Logged out successfully')}
  onError={(error) => console.error('Logout error:', error)}
/>

Parameters

| Parameter | Type | Description | |-------------|------------|--------------------------------------------------| | mode | string | The mode of the button (popup or redirect). | | onSuccess | function | Callback function triggered on successful logout.| | onError | function | Callback function triggered on logout error. |

This component is fully configurable and integrates seamlessly with the SDK.