集成 Builder Codes#

在 X Layer 上使用 Viem 或 Wagmi，为你的应用添加 ERC-8021 归因，将链上活动关联到你的应用。

前置条件#

需要 viem 2.45.0 或更高版本。定义你所需的 X Layer 链，并在整个配置中复用：

// chain.ts
import { defineChain } from "viem";

// Mainnet
export const xlayer = defineChain({
  id: 196,
  name: "X Layer",
  nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 },
  rpcUrls: {
    default: { http: ["https://rpc.xlayer.tech"] },
  },
  blockExplorers: {
    default: { name: "OKLink", url: "https://www.oklink.com/xlayer" },
  },
});

// Testnet
export const xlayerTestnet = defineChain({
  id: 1952,
  name: "X Layer Testnet",
  nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 },
  rpcUrls: {
    default: { http: ["https://testrpc.xlayer.tech"] },
  },
  blockExplorers: {
    default: { name: "OKLink", url: "https://www.oklink.com/x-layer-testnet" },
  },
});

获取你的 Builder Code

主网（Mainnet）： 前往 OKX 开发者门户，验证你的地址，然后在 Builder Code 页面创建你的 Builder Code。
测试网（Testnet）： 连接你的钱包，并在 Builder Code 注册合约上调用 registerAuto。需要测试网 OKB？使用水龙头。

客户端级配置#

在实际发送交易的客户端上统一配置 dataSuffix。对于浏览器钱包集成，推荐使用 Viem，因为配置好的 wallet client 也是用于发送交易的客户端。

Viem（推荐）#

安装依赖：

bash

npm i ox viem

创建并复用一个带有 dataSuffix 的 wallet client：

// client.ts
import { createWalletClient, custom } from "viem";
import { Attribution } from "ox/erc8021";
import { xlayer } from "./chain";

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"],
});

if (!window.ethereum) {
  throw new Error("No injected wallet found");
}

export const walletClient = createWalletClient({
  chain: xlayer,
  transport: custom(window.ethereum),
  dataSuffix: DATA_SUFFIX,
});

使用同一个客户端发送交易：

import { walletClient } from "./client";

const [account] = await walletClient.requestAddresses();

const hash = await walletClient.sendTransaction({
  account,
  to: "0x8d7c41aa990234b2d7e064df150a4228ed984648",
});

通过 walletClient 发送的每笔交易都会自动包含你的 Builder Code。

Wagmi#

对于连接器钱包，使用自定义连接器客户端，使 dataSuffix 应用到 useSendTransaction 使用的钱包支持客户端上。

安装依赖：

bash

npm i ox wagmi viem

添加一个返回带有 dataSuffix 的客户端的自定义注入连接器：

// config.ts
import { Attribution } from "ox/erc8021";
import { createClient, custom } from "viem";
import { createConfig, createConnector, http } from "wagmi";
import { injected } from "wagmi/connectors";
import { xlayer } from "./chain";

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"],
});

function injectedWithDataSuffix() {
  const baseInjected = injected();

  return createConnector((config) => {
    const connector = baseInjected(config);

    return {
      ...connector,
      async getClient({ chainId } = {}) {
        const id = chainId ?? (await connector.getChainId());
        const chain = config.chains.find((item) => item.id === id);
        const provider = await connector.getProvider({ chainId: id });
        const [account] = await connector.getAccounts();

        if (!chain) throw new Error(`Chain ${id} is not configured.`);
        if (!provider) throw new Error("Injected provider not found.");
        if (!account) throw new Error("No connected account found.");

        return createClient({
          account,
          chain,
          dataSuffix: DATA_SUFFIX,
          transport: (options) =>
            custom(provider)({
              ...options,
              retryCount: 0,
            }),
        });
      },
    };
  });
}

export const config = createConfig({
  chains: [xlayer],
  connectors: [injectedWithDataSuffix()],
  transports: {
    [xlayer.id]: http(),
  },
});

通过 useSendTransaction 发送的交易会从自定义连接器客户端继承你的 Builder Code：

tsx

// App.tsx
import { useSendTransaction } from "wagmi";

function SendButton() {
  const { sendTransaction } = useSendTransaction();

  return (
    <button
      onClick={() =>
        sendTransaction({
          to: "0x8d7c41aa990234b2d7e064df150a4228ed984648",
        })
      }
    >
      Send OKB
    </button>
  );
}

按交易配置#

如需更精细的控制，可直接在单笔交易上传入 dataSuffix，而非在客户端层面统一配置。

useSendTransaction#

tsx

import { useSendTransaction } from "wagmi";
import { Attribution } from "ox/erc8021";

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"],
});

function App() {
  const { sendTransaction } = useSendTransaction();

  return (
    <button
      onClick={() =>
        sendTransaction({
          to: "0x8d7c41aa990234b2d7e064df150a4228ed984648",
          dataSuffix: DATA_SUFFIX,
        })
      }
    >
      Send OKB
    </button>
  );
}

验证归因#

请参阅验证归因，了解确认交易是否已正确归因的步骤。

Builder Code 数据分析#

在 OKX 开发者门户中追踪你的 Builder Code 表现：

链上活动 —— 监控已归因的交易和调用量
用户获取 —— 衡量你的应用带来的新用户数
转化指标 —— 分析从曝光到链上行动的漏斗表现

利用这些数据优化你的集成，扩大你在 X Layer 上的用户群。