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.
Using the SDK
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
// }
});
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.
Configure the Components
Depending on the component you're looking to surface, choose between the following inputs:
Inputs for LoginWithDimo
& ShareVehiclesWithDimo
LoginWithDimo
& ShareVehiclesWithDimo
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
ExecuteAdvancedTransactionWithDimo
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.
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:
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:
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:
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
LogoutWithDimo
This is an optional decoupled component that developers can use to surface a "Log Out" button post-login. This signs out the current DIMO user from their account, and they must login again/re-authenticate in order for you to serve them privileged vehicle content in your application.
ExecuteAdvancedTransactionsWithDimo
This is a decouple component that developers can use post-login, will trigger login if user isn't logged in.
Integration Modes
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"]}
/>
Last updated
Was this helpful?