diff --git a/connection-types.md b/connection-types.md index 77e85f3..00402c5 100644 --- a/connection-types.md +++ b/connection-types.md @@ -22,15 +22,21 @@ This connection type is often used by organizations like VeBetterDAO, Cleanify, * Your users will need to login into other apps through ecosystem mode {% endhint %} -## 2) Privy Cross App +## 2) Privy Cross App (VeChain whitelabel) -When users integrate VeChain-kit using "Login with VeChain" and "Ecosystem" logins (eg: Mugshot and Greencart), this will be the default connection type. It is easily recognizable because login and wallet activities will open a secured popup window where the owner of the wallet will approve the actions. +This is the default connection type when your app **does not** pass a `privy` prop to `VeChainKitProvider`. Social logins (Google, Apple, X, Discord, GitHub, TikTok, LINE, and the multi-provider "Continue with VeChain" picker) run through VeChain's whitelabel popup at [`connect.vechain.org`](https://connect.vechain.org). The popup handles the OAuth handshake, decodes the transaction in plain language for the user, and posts the signed result back to your dApp.
-{% hint style="info" %} -With this type of connection, you can have social login in your app without actually paying Privy. -{% endhint %} +Why this is the default in v2.7+: + +* **Free social login** — no Privy account, no API keys, no billing. Drop a `{ method: 'google' }` button and it works. +* **One identity across the ecosystem** — the user's VeChain address is the same in every kit-integrated dApp, so balances, NFTs and domains follow them. +* **VeChain-branded** — the popup is whitelabeled (logo, palette, dark/light, 17 languages matching the kit). No Privy chrome leaks through. +* **Smart-contract-aware transaction review** — instead of raw hex, the user sees "Send 10 B3TR to vechain.vet" or "Vote FOR on a VeBetterDAO proposal" with verified-contract chips. +* **Auto-recovery from stale sessions** — if the connection record expires, the kit logs the user out and re-opens the login modal automatically. + +Use this option unless you have a specific reason to self-host Privy (see option 1). ## 3) Self-custody wallets diff --git a/docs/connection-types.md b/docs/connection-types.md index c46d131..3c84ee0 100644 --- a/docs/connection-types.md +++ b/docs/connection-types.md @@ -20,13 +20,19 @@ This connection type is often used by organizations like VeBetterDAO, Cleanify, * Your users will need to login into other apps through ecosystem mode {% endhint %} -## 2) Privy Cross App +## 2) Privy Cross App (VeChain whitelabel) -When users integrate VeChain-kit using "Login with VeChain" and "Ecosystem" logins (eg: Mugshot and Greencart), this will be the default connection type. It is easily recognizable because login and wallet activities will open a secured popup window where the owner of the wallet will approve the actions. +This is the default connection type when your app **does not** pass a `privy` prop to `VeChainKitProvider`. Social logins (Google, Apple, X, Discord, GitHub, TikTok, LINE, and the multi-provider "Continue with VeChain" picker) run through VeChain's whitelabel popup at [`connect.vechain.org`](https://connect.vechain.org). The popup handles the OAuth handshake, decodes the transaction in plain language for the user, and posts the signed result back to your dApp. -{% hint style="info" %} -With this type of connection, you can have social login in your app without actually paying Privy. -{% endhint %} +Why this is the default in v2.7+: + +* **Free social login** — no Privy account, no API keys, no billing. Drop a `{ method: 'google' }` button and it works. +* **One identity across the ecosystem** — the user's VeChain address is the same in every kit-integrated dApp, so balances, NFTs and domains follow them. +* **VeChain-branded** — the popup is whitelabeled (logo, palette, dark/light, 17 languages matching the kit). No Privy chrome leaks through. +* **Smart-contract-aware transaction review** — instead of raw hex, the user sees "Send 10 B3TR to vechain.vet" or "Vote FOR on a VeBetterDAO proposal" with verified-contract chips. +* **Auto-recovery from stale sessions** — if the connection record expires, the kit logs the user out and re-opens the login modal automatically. + +Use this option unless you have a specific reason to self-host Privy (see option 1). ## 3) Self-custody wallets diff --git a/docs/quickstart/login-customization.md b/docs/quickstart/login-customization.md index ebb9a6f..472f2ea 100644 --- a/docs/quickstart/login-customization.md +++ b/docs/quickstart/login-customization.md @@ -6,7 +6,7 @@ This guide covers the connect-modal authentication surface in VeChain Kit. From - **Custom in-house connection flow** for VeWorld and Sync2. Clicking a wallet button drives `@vechain/dapp-kit` programmatically (`setSource()` + `connect()`) and renders the kit's own "Waiting for signature…" view. WalletConnect's QR modal is preserved because that modal _is_ the QR. - **Granular `loginMethods`**: `veworld`, `sync2`, `wallet-connect`, `apple` are now first-class entries you can pin individually. The legacy `dappkit` value still works. -- **Variation A layout**: VeWorld primary filled (recommended), Google + Apple as outline secondary, "More options ⌄" link footer that opens an in-modal sub-view with overflow wallets / socials / ecosystem apps. +- **Variation A layout**: one recommended primary CTA (filled inverted + "recommended" dot) — usually VeWorld in the default config, but the dev controls which method gets the emphasis via `isPrimary`; the rest render as outline secondary. "More options ⌄" link footer opens an in-modal sub-view with overflow wallets / socials / ecosystem apps. - **Themeable accent**: spinner, focus rings and the "Waiting for signature…" headline read from `theme.accent`. ### Overview @@ -88,7 +88,7 @@ await initOAuth({ provider: 'google' }); // 'google' | 'apple' | 'github' | 'dis ### Configuring the grid: `loginMethods` -The order and shape of the connect-modal grid is controlled by `loginMethods` on ``. Each entry has a `method` and an optional `gridColumn` (1–4 — buttons span that many of the 4 columns). +The order and shape of the connect-modal grid is controlled by `loginMethods` on ``. Each entry has a `method`, an optional `gridColumn` (1–4 — buttons span that many of the 4 columns), and an optional `isPrimary` flag that controls which button gets the recommended-CTA treatment. ```tsx ``` +#### Recommended primary CTA — `isPrimary` + +One method per grid renders as the recommended CTA: filled inverted surface (dark on light mode, white on dark mode) with a small green dot. The rest render as outline secondary. Two ways the kit picks which: + +1. **Explicit** — any entry with `isPrimary: true` (excluding `more`, which is a footer link). If multiple entries set `isPrimary`, the first one wins. +2. **Implicit fallback** — when no entry sets `isPrimary`, the kit highlights the first visible method in the array. So a minimal config like `[{ method: 'google' }, { method: 'apple' }]` still gets Google as the recommended CTA without thinking about emphasis. + +Currently supported as primary: `veworld`, `google`, `apple`, `github`. Other methods can sit on the main grid but won't switch to the filled treatment when first / `isPrimary: true` — they keep their outline look. (Adding more is a one-prop change per button; open an issue if you need it.) + +```tsx +// Default: Google is primary because it's first. +loginMethods={[ + { method: 'google', gridColumn: 4 }, + { method: 'apple', gridColumn: 4 }, + { method: 'more', gridColumn: 4 }, +]} + +// Explicit: Apple is primary, Google is outline. +loginMethods={[ + { method: 'google', gridColumn: 4 }, + { method: 'apple', gridColumn: 4, isPrimary: true }, + { method: 'more', gridColumn: 4 }, +]} +``` + #### Method values | Method | Requires | Renders | diff --git a/docs/quickstart/provider-configuration.md b/docs/quickstart/provider-configuration.md index 92248a3..10bc684 100644 --- a/docs/quickstart/provider-configuration.md +++ b/docs/quickstart/provider-configuration.md @@ -75,10 +75,10 @@ export function VeChainKitProviderWrapper({ children }: { children: React.ReactN // Login Methods Configuration (variation A default) loginMethods={[ - { method: "veworld", gridColumn: 4 }, // primary CTA, recommended + { method: "veworld", gridColumn: 4, isPrimary: true }, // recommended CTA, filled + dot { method: "google", gridColumn: 4 }, { method: "apple", gridColumn: 4 }, - { method: "more", gridColumn: 4 }, // overflow sub-view (wallets / socials / ecosystem) + { method: "more", gridColumn: 4 }, // overflow sub-view (wallets / socials / ecosystem) ]} // Sponsor transactions @@ -135,12 +135,12 @@ feeDelegation: { #### Login Methods -Configure available authentication methods with a flexible grid layout. Each entry pins a `method` and an optional `gridColumn` (1–4) controlling how many of the 4 columns the button spans. +Configure available authentication methods with a flexible grid layout. Each entry pins a `method`, an optional `gridColumn` (1–4) controlling how many of the 4 columns the button spans, and an optional `isPrimary` flag that promotes the button to the recommended CTA (filled inverted surface + "recommended" green dot). If no entry sets `isPrimary`, the kit falls back to highlighting the first visible method. Only one button per grid is primary; `isPrimary` on the `more` footer link is ignored. The filled treatment currently supports `veworld`, `google`, `apple`, and `github`. ```typescript loginMethods: [ // --- Wallets (drives @vechain/dapp-kit programmatically; kit owns the UI) --- - { method: "veworld", gridColumn: 4 }, // primary CTA — filled, recommended dot + { method: "veworld", gridColumn: 4, isPrimary: true }, // recommended CTA — filled, dot { method: "sync2", gridColumn: 4 }, { method: "wallet-connect", gridColumn: 4 }, // triggers WC's own QR modal @@ -148,12 +148,17 @@ loginMethods: [ { method: "vechain", gridColumn: 4 }, // VeChain cross-app social login { method: "ecosystem", gridColumn: 4 }, // x2earn ecosystem apps footer - // --- Privy social (require `privy` configuration) --- - { method: "google", gridColumn: 4 }, - { method: "apple", gridColumn: 4 }, - { method: "github", gridColumn: 4 }, - { method: "email", gridColumn: 4 }, - { method: "passkey", gridColumn: 4 }, + // --- Social (routed through VeChain's whitelabel cross-app popup unless you pass `privy`) --- + { method: "google", gridColumn: 4 }, // works without `privy` (cross-app intent) + { method: "apple", gridColumn: 4 }, // works without `privy` + { method: "twitter", gridColumn: 4 }, // works without `privy` + { method: "discord", gridColumn: 4 }, // works without `privy` + { method: "github", gridColumn: 4 }, // works without `privy` + { method: "tiktok", gridColumn: 4 }, // works without `privy` + { method: "line", gridColumn: 4 }, // works without `privy` + { method: "email", gridColumn: 4 }, // requires your own `privy` (inline, no popup) + { method: "passkey", gridColumn: 4 }, // requires your own `privy` + { method: "sms", gridColumn: 4 }, // requires your own `privy` { method: "more", gridColumn: 4 }, // sub-view with overflow socials/wallets/ecosystem // --- Legacy --- @@ -206,7 +211,9 @@ function MyComponent() { ### Privy Integration (Optional) -To enable social login methods with your own Privy account: +Most social logins work without your own Privy account — the kit routes Google / Apple / X / Discord / GitHub / TikTok / LINE through VeChain's whitelabel cross-app popup automatically. Pass the `privy` prop only if you need email, passkey, SMS, additional OAuth providers, or want the login flow to render entirely inside your dApp instead of in a popup window. + +To enable those flows with your own Privy account: ```typescript