Commerce Kit wordt niet meer onderhouden
Commerce Kit-pakketten ontvangen geen updates of fixes meer. Gebruik voor nieuwe betalingsintegraties Solana Pay.
Het pakket @solana-commerce/connector biedt headless walletverbinding, gebouwd op de Wallet Standard. Het beheert walletdetectie, verbindingsstatus, accountbeheer en automatisch opnieuw verbinden. Het pakket is framework-agnostisch ontworpen en bevat React-bindings. Het is toegesneden op naadloos gebruik in Solana Commerce Kit en is compatibel met @solana/kit.
Walletverbinding
Installatie
pnpm add @solana-commerce/connector
Providerconfiguratie
ConnectorProvider
De component ConnectorProvider omhult je applicatie en levert de walletverbindingsstatus aan alle onderliggende componenten. Hij beheert één enkele ConnectorClient-instantie (singleton) die behouden blijft over mount-/unmount-cycli van componenten heen.
Props
Alle configuratie wordt doorgegeven via de prop config:
config(ConnectorConfig, optioneel) - Configuratieobject voor de connector. Alle velden zijn optioneel.
ConnectorConfig
Configuratieobject voor het gedrag van de walletverbinding.
Optionele velden
-
autoConnect(boolean) - Indientrue, wordt bij mount automatisch opnieuw verbonden met de laatst gebruikte wallet. De walletvoorkeur wordt opgeslagen in de geconfigureerde opslag (standaardlocalStorage). Standaard:false. -
debug(boolean) - Schakelt uitgebreide consolelogging in om verbindingsflows, accountwijzigingen en fouten te debuggen. Logs bevatten prefixen zoals[Connector]en[ConnectorProvider]. Standaard:false. -
accountPollingIntervalMs(number) - Pollinginterval in milliseconden voor het controleren op accountwijzigingen wanneer de wallet de functiestandard:eventsniet ondersteunt. De meeste moderne wallets ondersteunen events, dus polling is een terugvaloptie. Standaard:1500(1,5 seconden). -
storage(Storage) - Aangepaste opslagadapter voor het bewaren van walletvoorkeuren. Moet het volgende implementeren:getItem(key: string): string | nullsetItem(key: string, value: string): voidremoveItem(key: string): void
Standaard:
window.localStorageindien beschikbaar (alleen in de browser). Gebruik dit voor React Native (AsyncStorage) of aangepaste SSR-veilige opslag.
Providerarchitectuur
De provider gebruikt een singleton-patroon met referentietelling:
- Meerdere
ConnectorProvider-instanties delen dezelfdeConnectorClient - De client wordt bij de eerste mount aangemaakt en blijft behouden na unmounts
- Wanneer alle providers worden ge-unmount, wordt de opschoning 5 seconden uitgesteld om snelle remounts op te vangen
- Tijdens de opschoning wordt de wallet losgekoppeld en worden alle event listeners verwijderd
Dit ontwerp voorkomt dat de wallet wordt losgekoppeld bij routewijzigingen of componentupdates.
Hooks
useConnector()
De primaire hook voor toegang tot de walletverbindingsstatus en -acties. Moet worden gebruikt binnen een ConnectorProvider.
Retourneert een ConnectorSnapshot-object met:
Statuseigenschappen
-
wallets(WalletInfo[]) - Array van alle gedetecteerde Wallet Standard-compatibele wallets. Wordt automatisch bijgewerkt wanneer wallets worden geïnstalleerd of verwijderd. Elke wallet bevat metadata zoals naam, icoon en mogelijkheden. Zie WalletInfo. -
selectedWallet(Wallet | null) - Het momenteel verbonden Wallet Standard-walletobject.nullwanneer de verbinding is verbroken. Dit is de ruwe walletinstantie uit de Wallet Standard API. -
connected(boolean) - Verbindingsstatus.truewanneer een wallet is verbonden en accounts beschikbaar zijn. Gebruik dit voor conditionele UI-weergave. -
connecting(boolean) - Laadstatus tijdens het verbinden van de wallet.truetussen het aanroepen vanselect()en het ontvangen van het verbindingsresultaat. Gebruik dit om laadindicatoren te tonen of knoppen uit te schakelen. -
accounts(AccountInfo[]) - Array van accounts van de verbonden wallet. De meeste wallets bieden één account, maar sommige ondersteunen er meerdere. Wordt automatisch bijgewerkt via walletevents of polling. Zie AccountInfo. -
selectedAccount(string | null) - Het adres van het momenteel geselecteerde account (base58-gecodeerde publieke sleutel). Wanneer een wallet verbinding maakt met een nieuw account, wordt dat account automatisch geselecteerd. Anders blijft het eerder geselecteerde account behouden.
Actiemethoden
-
select((walletName: string) => Promise<void>) - Maakt verbinding met een wallet op naam (bijv."Phantom","Solflare"). De walletnaam moet exact overeenkomen met het veldnamevan een gedetecteerde wallet.Proces:
- Zet
connecting: true - Roept de functie
standard:connectvan de wallet aan - Haalt accounts op uit de wallet
- Abonneert zich op walletevents (of start polling als events niet beschikbaar zijn)
- Slaat de walletvoorkeur op in de geconfigureerde opslag
- Werkt de status bij met accounts en het geselecteerde account
Gooit: Fout als de wallet niet wordt gevonden, de wallet connect niet ondersteunt of de verbinding door de gebruiker is geweigerd.
- Zet
-
disconnect(() => Promise<void>) - Verbreekt de verbinding met de huidige wallet en ruimt de volledige status op.Proces:
- Zegt het abonnement op walletevents op
- Stopt accountpolling
- Roept de functie
standard:disconnectvan de wallet aan indien beschikbaar - Wist de geselecteerde wallet, accounts en het geselecteerde account
- Verwijdert de walletvoorkeur uit de opslag
Gooit nooit een fout (fouten worden gelogd als debug is ingeschakeld).
-
selectAccount((address: string) => Promise<void>) - Schakelt het geselecteerde account om naar een ander adres van de verbonden wallet. Als het adres niet in de huidige accounts-array staat, wordt opnieuw verbonden om bijgewerkte accounts op te halen.Gooit: Fout als er geen wallet is verbonden of het gevraagde account na het opnieuw verbinden niet wordt gevonden.
useConnectorClient()
Biedt directe toegang tot de onderliggende ConnectorClient-instantie voor geavanceerde use cases.
Retourneert: ConnectorClient | null - De singleton-clientinstantie, of null wanneer gebruikt buiten ConnectorProvider.
Use cases:
- Directe toegang tot
getConnectorState()voor imperatieve statuslezingen - Handmatig abonneren met
subscribe(listener)voor aangepaste statuslisteners destroy()aanroepen voor geforceerde opschoning (niet aanbevolen bij normaal gebruik)
Voorbeeld:
const client = useConnectorClient();// Get current state without triggering re-renderconst state = client?.getConnectorState();// Subscribe to state changes manuallyuseEffect(() => {if (!client) return;const unsubscribe = client.subscribe((state) => {console.log("Wallet state changed:", state);});return unsubscribe;}, [client]);
Typedefinities
WalletInfo
Metadata over een gedetecteerde wallet.
interface WalletInfo {wallet: Wallet; // Raw Wallet Standard wallet objectname: string; // Display name (e.g., "Phantom", "Solflare")icon?: string; // Data URL for wallet icon (base64 encoded)installed: boolean; // Always true (only installed wallets are discovered)connectable?: boolean; // Whether wallet supports required features}
Vereisten voor connectable: Een wallet is verbindbaar wanneer deze ondersteunt:
- de functie
standard:connect - de functie
standard:disconnect - Solana-chains (gedetecteerd doordat
wallet.chains"solana"bevat)
Niet-verbindbare wallets verschijnen in de wallets-array, maar kunnen niet worden geselecteerd.
AccountInfo
Informatie over een walletaccount.
interface AccountInfo {address: string; // Base58-encoded public keyicon?: string; // Account-specific icon (data URL)raw: WalletAccount; // Raw WalletAccount object from Wallet Standard}
Het veld raw biedt toegang tot aanvullende accounteigenschappen:
address: string- Base58-gecodeerde publieke sleutelpublicKey: Uint8Array- Ruwe bytes van de publieke sleutellabel?: string- Accountlabel (indien door de wallet geleverd)icon?: string- Accountspecifiek icoon (data-URL)chains: string[]- Ondersteunde chains voor dit accountfeatures: string[]- Ondersteunde functies voor dit account
ConnectorSnapshot
Het retourtype van useConnector(), dat status en acties combineert.
type ConnectorSnapshot = ConnectorState & {select: (walletName: string) => Promise<void>;disconnect: () => Promise<void>;selectAccount: (address: string) => Promise<void>;};interface ConnectorState {wallets: WalletInfo[];selectedWallet: Wallet | null;connected: boolean;connecting: boolean;accounts: AccountInfo[];selectedAccount: string | null;}
Detectie van accountwijzigingen
De connector detecteert automatisch wanneer walletaccounts veranderen (de gebruiker voegt accounts toe of verwijdert ze, of schakelt tussen accounts in de wallet). Hierbij worden twee strategieën gebruikt:
Eventgebaseerd (voorkeur)
Wanneer de wallet standard:events ondersteunt, abonneert de connector zich op change-events:
- Ontvangt realtime meldingen wanneer accounts veranderen
- Efficiënter (geen polling)
- Voegt accounts uit zowel het event als
wallet.accountssamen om wallets op te vangen die alleen het geselecteerde account in events opnemen
Polling als terugvaloptie
Wanneer events niet worden ondersteund, pollt de connector wallet.accounts:
- Controleert elke
accountPollingIntervalMs(standaard: 1500 ms) - Vergelijkt accountadressen om wijzigingen te detecteren
- Veroorzaakt alleen een re-render wanneer accounts daadwerkelijk veranderen
Logica voor accountselectie:
- Wanneer accounts veranderen, blijft het geselecteerde account behouden als het nog bestaat
- Als het geselecteerde account is verwijderd, wordt het eerste beschikbare account geselecteerd
- Bij het verbinden met een nieuw account (dat niet in de vorige accounts zat), krijgt het nieuwe account de voorkeur
Opslag en automatisch verbinden
Persistente opslag
De connector slaat één sleutel op in de geconfigureerde opslag:
- Sleutel:
arc-connector:lastWallet - Waarde: Walletnaam (bijv.
"Phantom")
Opslagoperaties zijn omgeven door try-catch om het volgende op te vangen:
- Sandboxed iframes waar
localStorageeen fout gooit - SSR-omgevingen waar
windowniet is gedefinieerd - React Native, waar
localStorageniet bestaat
Als de opslag mislukt, gaat de connector verder zonder persistentie (er worden geen fouten gegooid).
Gedrag van automatisch verbinden
Wanneer autoConnect: true:
- Leest bij mount de laatste walletnaam uit de opslag
- Wacht 100 ms (zodat wallets zich kunnen registreren)
- Roept
select(walletName)aan als de wallet is gedetecteerd - Als automatisch verbinden mislukt, wordt de ongeldige voorkeur uit de opslag verwijderd
Beveiligingsopmerking: De opgeslagen voorkeur is slechts een walletnaam (string) en geen gevoelige data. De wallet handelt authenticatie/autorisatie af via zijn eigen UI.
Gebruiksvoorbeelden
Eenvoudige walletknop
import { ConnectorProvider, useConnector } from "@solana-commerce/connector";function App() {return (<ConnectorProvider config={{ autoConnect: true }}><WalletButton /></ConnectorProvider>);}function WalletButton() {const { wallets, select, disconnect, connected, accounts, connecting } =useConnector();if (!connected) {return (<div><h3>Connect Wallet</h3>{wallets.map((wallet) => (<buttonkey={wallet.name}onClick={() => select(wallet.name)}disabled={!wallet.connectable || connecting}>{wallet.icon && (<img src={wallet.icon} alt={wallet.name} width={24} />)}{wallet.name}{!wallet.connectable && " (Unsupported)"}</button>))}</div>);}return (<div><p>Connected: {accounts[0]?.address.slice(0, 8)}...</p><button onClick={disconnect}>Disconnect</button></div>);}
Accountkiezer voor meerdere accounts
function AccountSelector() {const { accounts, selectedAccount, selectAccount } = useConnector();if (accounts.length <= 1) return null;return (<selectvalue={selectedAccount || ""}onChange={(e) => selectAccount(e.target.value)}>{accounts.map((account) => (<option key={account.address} value={account.address}>{account.raw.label || `${account.address.slice(0, 8)}...`}</option>))}</select>);}
Verbindingsmonitoring
function ConnectionMonitor() {const { connected, selectedWallet, accounts } = useConnector();useEffect(() => {if (connected) {console.log("Wallet connected:", selectedWallet?.name);console.log("Accounts:",accounts.map((a) => a.address));}}, [connected, selectedWallet, accounts]);return null;}
Ondersteunde wallets
De connector ondersteunt alle wallets die de Wallet Standard implementeren, waaronder:
- Phantom
- Solflare
- Backpack
- Glow
- Brave Wallet
- Coinbase Wallet
- Elke andere Wallet Standard-compatibele wallet
Wallets worden automatisch gedetecteerd wanneer ze zich registreren bij de Wallet Standard API (geen configuratie nodig).
Headless gebruik (zonder React)
Gebruik voor niet-React-applicaties of server-side gebruik ConnectorClient rechtstreeks:
import { ConnectorClient } from "@solana-commerce/connector";const connector = new ConnectorClient({autoConnect: true,debug: true});// Get current stateconst state = connector.getConnectorState();console.log("Available wallets:", state.wallets);// Connect to a walletawait connector.select("Phantom");// Subscribe to state changesconst unsubscribe = connector.subscribe((state) => {console.log("Connected:", state.connected);console.log("Accounts:", state.accounts);});// Switch accountawait connector.selectAccount("account-address-here");// Disconnectawait connector.disconnect();// Cleanup (removes all listeners and timers)connector.destroy();
Opmerking: ConnectorClient beheert zijn eigen status en veroorzaakt nooit React-re-renders. Je moet handmatig abonneren op statuswijzigingen.
Is this page helpful?