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.

$3

`
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
},
});
`

$3

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

`



`

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

$3

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)

$3

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

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

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
/>

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
/>

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"]}
/>
`

$3

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

`javascript
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 ? (
mode="popup"
onSuccess={(authData) => console.log("Success:", authData)}
onError={(error) => console.error("Error:", error)}
permissionTemplateId={"1"}
// expirationDate={} // Optional ISO string
/>

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"]}
/>
) : (
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

$3

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 |

$3

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 |

$3

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:
`typescript
permissions={[
'NONLOCATION_TELEMETRY',
'CURRENT_LOCATION',
'STREAMS'
]}
// other props...
/>
`

Using the Permissions enum (recommended for TypeScript projects):
`typescript
import { Permissions } from '@dimo-network/login-with-dimo';

// ...

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

$3

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 |

$3

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

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

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.