D3 Embed

D3 Embed Overview

A customizable widget that can be embedded directly into your platform with minimal code, D3 Embed will make it easier than ever to integrate Name Token sales into your platform. D3 Embed is a simple yet powerful tool designed to seamlessly fit into your website or application, allowing your users to interact with D3 services directly from your site.

The widget will enable users to:

• Search for domain names: Let your users browse and discover the perfect domain name in just a few clicks.

• Purchase domains: The widget supports purchasing with various crypto currencies/blockchains (fiat coming soon), giving your users flexibility in payment options.

• Customization options: Keep your own branding and style by easily customizing the widget’s look and feel to match your site. You can even customize checkout options, making it fit perfectly with your existing payment processes.

• Instant integration: No complex coding required. The widget is designed to be plug-and-play, allowing you to embed it easily with just a few lines of code.

Why Integrate the D3 Widget?

• Seamless Experience: Keep your users on your site while offering them the full power of D3’s domain services.

• Boost Engagement: By embedding the widget, you’ll provide a valuable feature that keeps your users engaged with your platform.

• Monetization Opportunities: Incorporate the widget into your monetization strategy, allowing you to offer premium services without heavy development overhead.

Getting Started

• Demo Widget

• Sample Source Code (See our github repository for example integration of the widget)

• Detailed Steps 👇

Sign up at D3 Developer Dashboard to get your own API keys today.

1. Installation

Install the widget package using npm, yarn or pnpm.

NPM

npm install @d3-inc/marketplace-widget

Yarn

yarn add @d3-inc/marketplace-widget

Peer Dependencies

Make sure the peer dependencies required by the widget are correctly installed in your app.

"@tanstack/react-query": "^5.56.2",
"react": "^18.0",
"react-dom": "^18.0",
"zustand": "^4.5.0"

Styles

Import the styles in the root of the app, so these are accessible by the widget.

import '@d3-inc/marketplace-widget/styles.css';

2. Usage

Scenario 1: Install widget with built-in Connect Wallet implementation

This is the quickest and simplest integration scenario. The D3 widget has complete support for wallet management within the widget, which will handle the wallet connection, chains and transactions management.

The widget uses wagmi and viem for EVM wallet management. So, if your app already uses the wagmi library, the widget will try to reuse the same config. You can also provide additional props for use in the wagmi config.

The user can connect and disconnect wallet from the widget. The widget doesn't persist the connect wallet, so on page refresh the user needs to re-connect the wallet.

We support the connectors below in the widget.

• injected
• coinbaseWallet
• walletConnect

You can check more details in the wagmi docs.

Make sure to pass a valid wallet-connect developer key in the config, which will be used in the wallet-connect connector. You can get a wallet-connect developer key from Reown Cloud | Sign In

<D3Widget
  appName="Your app name"
  config={{
    appearance: 'light',  // light | dark | auto
    apiKey: d3ApiKey,  // Get your api key from https://developers.d3.app
    tlds: [],  // One or more TLDs or leave blank to list all available TLDs
    apiEndpoint: 'https://api-public.d3.app',
    walletConfig: {
      walletConnectKey,  // Optional. If provided, widget will use wallet-connect
    },
  }}
/>

You can pass some additional props for connect wallet flow

walletConfig: {
  walletConnectKey: string;
  walletConnect?: WalletConnectParameters;
  coinbase?: CoinbaseWalletParameters;
  metaMask?: MetaMaskParameters;
}
//Above types are being re-used from the @wagmi/connectors. You can check more details here

Scenario 2: Install widget using callback method

This integration mode of the d3 widget doesn't initialize any internal wallet modules and uses the callback approach to handle the purchase and cart management. This option is helpful in case your dApp already has wallet and blockchain integrations and you don't want to include any additional web3 libs.

To integrate the widget using callback method, you can initialize the widget like below:

import { D3Widget } from '@d3-inc/marketplace-widget';

<D3Widget
  appName="Your app name"
  config={{
    appearance: 'light',
    apiKey: d3ApiKey,
    showRecommendations: true,
    // This is important to pass in the initialization, which tells the widget about the integration mode.
    walletAddress: address,
    // callback to handle the crypto transaction on this yourself. Refer to below section to learn more.
    onPurchaseInit: handlePurchaseTransaction,
    tlds: widgetTlds,
    apiEndpoint: 'https://api-public.d3.app',
  }}
/>

// Purchase transaction callback will receive 3 parameters
import type { CheckoutCallback, PaymentOption } from '@d3-inc/marketplace-widget';

type PurchaseTransactionProps = {
  handleOnSuccess: (receipt: TransactionReceipt | undefined) => void;
  handleOnError: (error: BaseError | string) => void;
  transactionVoucher: CheckoutCallback;
};

  async function handleCryptoCheckout({
    transactionVoucher,
    handleOnError,
    handleOnSuccess,
  }: HandleCryptoCheckoutProps) {
    // Your logic related to the crypto transaction goes here
    // Please check the detailed types of CheckoutCallback
  }

Below props should be provided to widget for purchase flow

• walletAddress: (0x${string} | string)

  • this will be used for the purchase transaction

  • make sure to keep it updated in the host app, so only the currently connected wallet is used for purchase transaction.

• onPurchaseInit:callback with below parameters

onPurchaseInit: ({
  transactionVoucher,
  handleOnError,
  handleOnSuccess
}) => Promise<void>

// the widget exports the types for these arguments 
import type { CheckoutCallback, PaymentOption } from '@d3-inc/marketplace-widget';

// than you can use these types in the callback (if your project uses typescript)
// below is the detailed overview of the transactionVoucher parameter

type PaymentOption = {
  tokenAddress: string;
  contractAddress: string;
  symbol: string;
  icon: string;
  price: number;
  addressType: WalletAddress;
  chainId: string; // this is important to check the chain, where this payment option is available on
};

type CheckoutOrderRequestResponse = {
  voucher: {
    paymentId: string;
    amount: string;
    token: `0x${string}` | string;
    buyer: `0x${string}` | string;
    voucherExpiration: number;
    orderId: string;
    names: {
      label: string;
      tld: string;
      registry: `0x${string}` | string;
      expirationTime: number;
      owner: `0x${string}` | string;
      renewal: false;
    }[];
  };
  signature: `0x${string}` | string;
};

type CheckoutCallback = CheckoutOrderRequestResponse & {
  selectedPaymentToken: PaymentOption;
};

Since the widget relies on the host app to determine the transaction response, please make sure to properly include the handleOnSuccess and handleOnError relevant states. Otherwise, the widget might not be able to show any success or error.

In the callback, chainId is also returned in the paymentOption. Please make sure to verify the user is on the same chain before proceeding with the transaction to avoid any unexpected failures and issues in the transaction.

You can find a complete example of callback approach (with wagmi and viem) in the examples folder (link will be added).

Widget API

• apiKey (string)

  • You can get the apikey from the D3 Developers Dashboard . Make sure to set the correct permissions for this key.
• tlds (string | string[])

  • required

  • if you want to use multiple supported tlds in the widget, you can pass an array. Make sure to set the permissions correctly in the dashboard for the widget to use multiple tlds. See here for full list of supported tlds.
• appName (string)

  • optional

  • This is helpful to show in the wallet transactions, when the widget is used alongside the connect wallet

• appearance (auto | dark | light)

  • optional

  • defaults to auto

  • if auto, this will use the system’s theme

  • if light, the widget will be shown in light theme

  • if dark, the widget will use the dark theme for the UI

• apiEndpoint (string)

  • optional

  • defaults to https://api-public.d3.app

• showRecommendations (boolean)

  • optional

  • defaults to false

  • if true, the widget will also show the AI Recommendationsbased on the user’s search input. These are AI generated suggestions and at most 20 results will be shown in the widget.

• walletAddress: (0x${string} | string)

  • required (when callback approach is used)

  • this will be used for the purchase transaction

  • make sure to keep it updated in the host app, so only the currently connected wallet is used for purchase transaction.

• onPurchaseInit:callback with below parameters:

onPurchaseInit: ({
  transactionVoucher,
  handleOnError,
  handleOnSuccess
}) => Promise<void>

// the widget exports the types for these arguments 
import type { CheckoutCallback, PaymentOption } from '@d3-inc/marketplace-widget';

// than you can use these types in the callback (if your project uses typescript)
// below is the detailed overview of the transactionVoucher parameter

type PaymentOption = {
  tokenAddress: string;
  contractAddress: string;
  symbol: string;
  icon: string;
  price: number;
  addressType: WalletAddress;
  chainId: string; // this is important to check the chain, where this payment option is available on
};

type CheckoutOrderRequestResponse = {
  voucher: {
    paymentId: string;
    amount: string;
    token: `0x${string}` | string;
    buyer: `0x${string}` | string;
    voucherExpiration: number;
    orderId: string;
    names: {
      label: string;
      tld: string;
      registry: `0x${string}` | string;
      expirationTime: number;
      owner: `0x${string}` | string;
      renewal: false;
    }[];
  };
  signature: `0x${string}` | string;
};

type CheckoutCallback = CheckoutOrderRequestResponse & {
  selectedPaymentToken: PaymentOption;
};

Supported TLDs

TLD	Blockchain
shib	Shibarium
core	Core
vic	Viction
ape	ApeChain