React Component

React Component SDK

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

npm: @dimo-network/login-with-dimonpm

Login with DIMO on NPM Registry

---

Using the SDK

1

Installation

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

2

Initialization

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

// Initialize the State Variables
const { 
  isAuthenticated, 
  getValidJWT, 
  email, 
  walletAddress, 
  getEmail 
} = useDimoAuthState();

// Initialize the SDK
initializeDimoSDK({
  clientId: "<dev_license_clientId>",
  redirectUri: "<dev_license_redirectUri>",
  // OPTIONAL
  // apiKey: "<dev_license_apiKey>",
  // environment: "<environment>", 
  // options: {
  //    forceEmail: true, //BY DEFAULT, this is False - users won't have to share email
  // }
});

Parameter	Type	Details
clientId*	String	A valid client ID registered with your Developer License.
redirectUri*	String	A valid redirect URI registered with your Developer License.
apiKey	String	Optional API key of your Developer License. This is currently not in use and reserved for future applications.
environment	String	Environment where your app is registered to. Defaults to production if not indicated. Supports development or production at the moment.
options	Object	Additional options for the Login with DIMO Component. Currently supports forceEmail:true, which requires users to opt into email sharing when logging in. If excluded, defaults to optional email sharing on login.

3

Import the Components

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

In your React app, import the different components as needed and drop in the component of interest with the following input configurations.

4

Configure the Components

Depending on the component you're looking to surface, choose between the following inputs:

Inputs for LoginWithDimo & ShareVehiclesWithDimo

Parameter	Type	Details
mode*	String	One of the two available modes: popup or redirect.
onSuccess*	Callback	Callback function called when the authData is returned for popup mode. Example for authData: { token: <access_token> } For redirect mode, the access_token is in the redirect URI. Example for redirect: https://your-site.com/redirect?token=<access_token>&email=<user_email>
onError*	Callback	Callback function called when error occurs.
permissionTemplateId	String	Optional template ID of the SACD permissions template on IPFS. If undefined, no permissions flow will be triggered for the end users. For ShareVehiclesWithDimo component, this is required as sharing requires permission templates.
utm	String	Optional parameter for configuring UTMs. Useful for campaign tracking. Example: <LoginWithDimo utm="utm_campaign=dimo" /> will redirect to: https://redirecturi.com/?utm_campaign=dimo
vehicles	[String]	Optional array of vehicle tokenId's to target for the logged in user. If vehicles is not provided, the flow will pull all available vehicles. This also filters out any vehicle tokenId that doesn't belong to the signed-in user.
vehicleMakes	[String]	Optional array of vehicle makes to filter for compatibility with your app. If vehicleMakes is not provided, all available vehicles will be marked as compatible. Example: [ 'Tesla', 'Audi', 'Lexus' ]
powertrainTypes	[String]	Optional array of powertrain types to filter for compatibility with your app. If powertrainTypes is not provided, all vehicle types will be marked as compatible. Example: ['BEV', 'HEV', 'PHEV', 'ICE', 'FCEV']
expirationDate	[String]	Optional parameter to explicitly specify an expiration date for permissions in the ISO8601 format (YYYY-MM-DD).
authenticatedLabel	[String]	Optional parameter to override default button label text for authenticated users.
unAuthenticatedLabel	[String]	Optional parameter to override default button label text for unauthenticated users.

For more information on these inputs, see: Core Functionalities

Inputs for ExecuteAdvancedTransactionWithDimo

Parameter	Type	Details
mode*	String	One of the two available modes: popup or redirect.
onSuccess*	Callback	Callback function called when data is returned for popup mode. Example: data: { token: <access_token>; transactionHash: <tx_hash>; transactionReceipt: <tx_receipt>; }
onError*	Callback	Callback function called when error occurs.
address*	String	The 0x address of the smart contract being executed.
abi*	Any	An array of JSON representing the ABI of the advanced functions of interest.
functionName*	String	The name of the function being called.
args*	[String]	The arguments being passed into the function call.
value	String	Optional number in wei of the native currency sent as a part of the transaction.

5

Build your app

Now that you've reached this step, all you need to do is finish building your app and interact with the components. Depending on what you wish your users see, reconfigure as necessary.

6

Voila, you're all done 🎉

Congratulations for reaching this step, you're one huge step closer to launching an integration with DIMO!

Next Steps:

If you've made it this far, you've successfully set up Login with DIMO. To access vehicle data after a user has shared access with you, we recommend implementing using the Data SDK on the backend. When a user authenticates via the Login component, their walletAddress is returned - meaning you're ready to query the Identity API to obtain the Token IDs of the vehicles that were shared with you.

Take me to the Data SDK Docs →

Additional Resources:

State Variables

DimoAuthProvider is used to get the auth state value from the SDK, as well as to keep track of the user email, Global Account public address, and the User JWT.

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

<DimoAuthProvider>
    <SomeComponentThatNeedsDimoState/>
<DimoAuthProvider/>

Component Types:

LoginWithDimo

When permissionTemplateId are provided:

User has no vehicles connected	User has all vehicles shared	User has some vehicles not shared
Shows "No vehicles connected" with a Continue Button	Shows "All vehicles have been shared" with a Continue Button	Show list of all vehicles for permission sharing

When permissionTemplateId are NOT provided. Since permissions are not requested, developers can couple this with the ShareVehiclesWithDimo component post-login:

User has no vehicles connected	User has all vehicles shared	User has some vehicles not shared
Skips permission sharing	Skips permission sharing	Skips permission sharing

ShareVehiclesWithDimo

This is a decoupled component that developers can use post-login, will trigger login if user isn't logged in:

User has no vehicles connected	User has all vehicles shared	User has some vehicles not shared
Shows "No vehicles connected" with a Continue Button	Shows "All vehicles have been shared" with a Continue Button	Show list of all vehicles for permission sharing

ExecuteAdvancedTransactionsWithDimo

This is a decouple component that developers can use post-login, will trigger login if user isn't logged in.

Integration Modes

Mode	Description
popup	The popup mode surfaces a React button component that opens up a browser pop-up (new window) containing the Login with DIMO interface.
redirect	The redirect mode surfaces a React button component that redirects the users to the Login with DIMO interface.

Usage Example

<LoginWithDimo
    mode="popup"
    onSuccess={(authData) => console.log("Success:", authData)}
    onError={(error) => console.error("Error:", error)}
    // 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
    permissionTemplateId={permissionsEnabled ? "1" : undefined}
    // Optionally, specify vehicles (uncomment the line below to use it)
    // vehicles={["585","586"]}  // Specify the vehicles to be accessed after login
    utm="utm_campaign=dimo" // OPTIONAL            
/>

 <ShareVehiclesWithDimo
    mode="popup"
    onSuccess={(authData) => console.log("Success:", authData)}
    onError={(error) => console.error("Error:", error)}
    //REQUIRED: "1" is the template for all SACD permissions
    permissionTemplateId={"1"}
    // OPTIONAL, specify vehicles (uncomment the line below to use it)
    // vehicles={["585","586"]}  // Specify the vehicles to be accessed when triggered
    expirationDate="2062-12-12T18:51:00Z" // ISO 8601 format 
    // OPTIONAL, defaults to 100 year if not specified  
    utm="utm_campaign=dimo" // OPTIONAL  
/>      

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