Login with DIMO

Expedite your build using the Login with DIMO components

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.

Key Features

Pre-built components: The SDK offers pre-built React components that can be imported easily.
Flexibility with multiple integration modes: The components are designed to be flexible with multiple integration modes, such as embed, popup, or redirect.
Login with DIMO: End users are presented with a email login field, and an OTP will be sent to the email for authentication. A passkey prompt will be triggered after the OTP for either setup or login. .
Integration with the Transactions SDK: The React components seamlessly integrate with the Transactions SDK, allowing you to leverage the SDK's features and functionalities such as creating a vehicle and sharing vehicle permissions, etc.

This SDK utilizes Accounts API for developers and manages to connect to the user's DIMO account. Once connected, it further integrates with the Transactions SDK to perform operations associated with the user's vehicles and permissions.

Using the SDK

Installation

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

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

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.

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.

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 three available modes: popup, embed, or redirect.

onSuccess*

Callback

Callback function called when the authData is returned for popup and embed modes. 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.

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, currently supports only one vehicle make, such as audi or tesla. If vehicleMakes is not provided, the flow will pull all available vehicles.

expirationDate

[String]

Expiration date for permissions in the ISO8601 format (YYYY-MM-DD).

Defaults to 1 year from the current time if not specified.

Inputs for `ExecuteAdvancedTransactionWithDimo`

Parameter

Type

Details

mode*

String

One of the three available modes: popup, embed, or redirect.

onSuccess*

Callback

Callback function called when data is returned for popup and embed modes. 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. The number in wei of the native currency sent as a part of the transaction.

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.

Voila, you're all done 🎉

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

Don't Use React?

Developer Notes

If you don't use the React framework, you can still build a button in your tech stack and redirect the users to the following URLs depending on the flow of interest.

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

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

embed

The embed mode basically embeds an iframe HTML element that surfaces the Login with DIMO interface. In this mode, the JWT returned is considered a 3rd party cookie so be aware of the user's browser settings.

By default, browsers like Chrome and Firefox allows 3rd party cookies, but browsers like Safari and Brave blocks them.

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.

Core Functionalities

DIMO Account Creation / Logins

Login with DIMO allow developers to surface an interface for the end users to authenticate by integrating with the Accounts API. This functionality sets up the smart contract wallet for the end user, giving full root access to the user (and only the user), enabling logins across all DIMO platforms with the use of a passkey.

DIMO Check-in

Learn more about how passkey is more secure and the future for Internet security in this Google blog: https://blog.google/inside-google/googlers/ask-a-techspert/how-passkeys-work/

This is an optional functionality that you can enable on the Component SDK either by coupling it with the login flow or decoupling it onto a button of its own.

[Usage 1] When this is enabled in the LoginWithDimo component, logged in users are prompted with a share permission(s) page to share their selected vehicles with your application.

[Usage 2] When you surface a second component in ShareVehiclesWithDimo, logged in users will need to click on this button to trigger the sharing flow. This allows developers to feed in information in between the login and the permissions flow.

Expiration Dates

This is another optional property that you can enable on the Component SDK, which, if added, sets an expiration date on vehicle privileges granted by a user. If not explicitly added, the expiration date for a vehicle's privileges defaults to 1 year. In TypeScript, you can construct these dates like so:

const customDate = new Date(Date.UTC(2062, 11, 12, 18, 51)); // Note: Month is zero-based
const iso8601String: string = customDate.toISOString();

Developer Notes

While optional, it is recommended that you include an expirationDate in your component. If not included in the component, it will default to 1 year. Once the expiration date passes, you will no longer have privileged access to vehicles that have previously been shared with you, and users will need to re-share their vehicles with your app. It's up to developers to communicate to their users when they may need to re-share their vehicles.

Advanced Transactions

This is an optional functionality where you can trigger any ABI calls.

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

 <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 1 year if not specified  
/>

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

PreviousTypeScript: Data SDK NextPermissions Contract: SACD

Last updated 19 days ago

Key Features

Using the SDK

Installation

Initialization

Import the Components

Configure the Components

Inputs for LoginWithDimo & ShareVehiclesWithDimo

Inputs for ExecuteAdvancedTransactionWithDimo

Build your app

Voila, you're all done 🎉

Don't Use React?

State Variables

Component Types

LoginWithDimo

ShareVehiclesWithDimo

ExecuteAdvancedTransactionsWithDimo

Integration Modes

Core Functionalities

DIMO Account Creation / Logins

Vehicle Permission Sharing

Expiration Dates

Advanced Transactions

Usage Example

Inputs for `LoginWithDimo` & `ShareVehiclesWithDimo`

Inputs for `ExecuteAdvancedTransactionWithDimo`