Skip to content

Commit c1275a5

Browse files
MananTankMananTank
committed
[MNY-354] Portal: Add Buy Widget iframe docs (#8614)
<!-- ## title your PR with this format: "[SDK/Dashboard/Portal] Feature/Fix: Concise title for the changes" If you did not copy the branch name from Linear, paste the issue tag here (format is TEAM-0000): ## Notes for the reviewer Anything important to call out? Be sure to also clarify these in your comments. ## How to test Unit tests, playground, etc. --> <!-- start pr-codex --> --- ## PR-Codex overview This PR introduces the `Buy Widget`, enhancing the portal with a new iframe component for purchasing crypto. It includes documentation, features, and examples for users to integrate the widget easily. ### Detailed summary - Added `IframeCodePreview` component in `iframe-code-preview.tsx`. - Updated sidebar links to reflect the new `Buy Widget` and `Swap Widget`. - Created documentation for the `Buy Widget` in `page.mdx`, detailing features and integration. - Added example usage of the `BuyWidget` component in `react/page.mdx`. - Developed `iframe/page.mdx` with customization options and event listening for the widget. > ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}` <!-- end pr-codex --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added an iframe embed preview with code/preview tabs for trying the Buy widget. * **Documentation** * Added comprehensive Buy widget docs (overview, React and iframe guides, examples, customization, event listening, live playgrounds). * **Chores** * Updated site navigation: Widgets section reorganized to list Swap, Buy, and Checkout widgets with updated links. <sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub> <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 2778745 commit c1275a5

File tree

5 files changed

+414
-8
lines changed

5 files changed

+414
-8
lines changed

‎apps/portal/src/app/bridge/buy-widget/iframe/iframe-code-preview.tsx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { CodeBlock, Tabs, TabsContent, TabsList, TabsTrigger } from "@doc";
2+
3+
export function IframeCodePreview(props: { src: string }) {
4+
const includesImage = props.src.includes("image=");
5+
const height = includesImage ? "850px" : "700px";
6+
return (
7+
<Tabs defaultValue="code">
8+
<TabsList>
9+
<TabsTrigger value="code">Code</TabsTrigger>
10+
<TabsTrigger value="preview">Preview</TabsTrigger>
11+
</TabsList>
12+
<TabsContent value="code">
13+
<CodeBlock
14+
code={`\
15+
<iframe
16+
src="${props.src}"
17+
height="${height}"
18+
width="100%"
19+
style="border: 0;"
20+
/>`}
21+
lang="html"
22+
/>
23+
</TabsContent>
24+
<TabsContent value="preview">
25+
<iframe
26+
title="Buy widget iframe"
27+
src={props.src}
28+
height={height}
29+
className="rounded-xl"
30+
width="100%"
31+
style={{ border: 0 }}
32+
/>
33+
</TabsContent>
34+
</Tabs>
35+
);
36+
}

‎apps/portal/src/app/bridge/buy-widget/iframe/page.mdx‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
import {
2+
ArticleIconCard,
3+
Details,
4+
createMetadata,
5+
} from "@doc";
6+
import { IframeCodePreview } from "./iframe-code-preview";
7+
import { PlayIcon } from "lucide-react";
8+
9+
export const metadata = createMetadata({
10+
image: {
11+
title: "Buy widget iframe",
12+
icon: "payments",
13+
},
14+
title: "Buy widget iframe",
15+
description: "Add a widget to let users buy crypto in your app using an iframe",
16+
});
17+
18+
# Buy widget iframe
19+
20+
The Buy widget iframe makes it easy for users to purchase crypto tokens in your app. Just add an iframe to your HTML and get a fully customizable buy widget - no build setup required.
21+
22+
## Features
23+
24+
- Purchase crypto tokens with fiat (credit/debit cards)
25+
- Cross-chain token swaps across 90+ blockchains
26+
- Display product information (title, description, image)
27+
- Customizable UI with dark and light mode support
28+
- Display fiat values in multiple currencies
29+
30+
31+
### Example
32+
33+
34+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget" />
35+
36+
37+
## Try it out
38+
39+
<ArticleIconCard
40+
title="Buy Widget Playground"
41+
description="Try out the Buy Widget in our live playground"
42+
icon={PlayIcon}
43+
href="https://playground.thirdweb.com/bridge/buy-widget?tab=iframe"
44+
/>
45+
46+
## Options
47+
48+
You can customize the buy widget using query parameters as mentioned below.
49+
50+
51+
### Theme
52+
53+
By default the widget uses the "dark" theme. You can set the light theme by passing the `theme=light` query parameter.
54+
55+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?theme=light" />
56+
57+
58+
### Product Information
59+
60+
You can display product information by passing `title`, `description`, and `image` query parameters. Each of these parameters are optional.
61+
62+
Make sure to URI encode the parameters if they contain special characters.
63+
64+
<Details summary="Example">
65+
66+
* title: `"Something"`
67+
* description: `"Description of something goes here"`
68+
* image: `"https://picsum.photos/600/300"`
69+
* price: 0.01 ETH on Base
70+
71+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?chain=8453&amount=0.01&title=Something&description=Description%20of%20something%20goes%20here&image=https%3A%2F%2Fpicsum.photos%2F600%2F300" />
72+
73+
</Details>
74+
75+
76+
### Currency
77+
78+
By default the fiat value of the token amounts is displayed in USD. You can change the currency by setting the `currency` query parameter.
79+
80+
<Details summary="Supported Currencies">
81+
82+
- `USD` - US Dollar (default)
83+
- `EUR` - Euro
84+
- `GBP` - British Pound
85+
- `JPY` - Japanese Yen
86+
- `KRW` - Korean Won
87+
- `CNY` - Chinese Yuan
88+
- `INR` - Indian Rupee
89+
- `NOK` - Norwegian Krone
90+
- `SEK` - Swedish Krona
91+
- `CHF` - Swiss Franc
92+
- `AUD` - Australian Dollar
93+
- `CAD` - Canadian Dollar
94+
- `NZD` - New Zealand Dollar
95+
- `MXN` - Mexican Peso
96+
- `BRL` - Brazilian Real
97+
- `CLP` - Chilean Peso
98+
- `CZK` - Czech Koruna
99+
- `DKK` - Danish Krone
100+
- `HKD` - Hong Kong Dollar
101+
- `HUF` - Hungarian Forint
102+
- `IDR` - Indonesian Rupiah
103+
- `ILS` - Israeli New Sheqel
104+
- `ISK` - Icelandic Krona
105+
106+
</Details>
107+
108+
#### Example
109+
110+
Show fiat values in Euro (EUR) in the widget.
111+
112+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?currency=EUR" />
113+
114+
### Payment Methods
115+
116+
By default, the widget enables both crypto and card (fiat) payment methods.
117+
118+
You can customize which payment methods are available by setting the `paymentMethods` query parameter.
119+
120+
Accepted values:
121+
- `crypto` - Enable crypto payments only
122+
- `card` - Enable card (fiat) payments only
123+
124+
<Details summary="Only enable crypto payments">
125+
126+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?paymentMethods=crypto" />
127+
128+
</Details>
129+
130+
131+
<Details summary="Only enable card payments">
132+
133+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?paymentMethods=card" />
134+
135+
</Details>
136+
137+
### thirdweb branding
138+
139+
By default, the widget displays thirdweb branding at the bottom. You can hide this by setting the `showThirdwebBranding` query parameter to `false`.
140+
141+
<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?showThirdwebBranding=false" />
142+
143+
## Listening for Events
144+
145+
The buy widget iframe sends events to the parent window using `postMessage` when a purchase succeeds or fails.
146+
147+
You can listen for these events to handle the purchase result in your application.
148+
149+
```js
150+
window.addEventListener("message", (event) => {
151+
152+
// verify that message is from thirdweb buy widget iframe
153+
if (
154+
event.origin === "https://thirdweb.com" && event.data.source === "buy-widget"
155+
) {
156+
157+
if (event.data.type === "success") {
158+
console.log("Purchase successful!");
159+
}
160+
161+
if (event.data.type === "error") {
162+
console.error("Purchase failed with error:", event.data.message);
163+
}
164+
}
165+
166+
});
167+
```
168+

‎apps/portal/src/app/bridge/buy-widget/page.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import {
2+
Details,
3+
createMetadata,
4+
DocImage,
5+
} from "@doc";
6+
import { ArticleIconCard } from "@doc";
7+
import { FrameIcon, PlayIcon } from "lucide-react";
8+
import { ReactIcon } from "@/icons";
9+
10+
export const metadata = createMetadata({
11+
image: {
12+
title: "Buy widget",
13+
icon: "payments",
14+
},
15+
title: "Buy widget",
16+
description: "Add a widget to let users buy crypto in your app",
17+
});
18+
19+
# Buy widget
20+
21+
The Buy widget makes it easy for users to purchase crypto tokens in your app. It supports both fiat payments (credit/debit cards) and crypto payments, with cross-chain support across 90+ blockchains.
22+
23+
## Features
24+
25+
- Purchase crypto tokens with fiat (credit/debit cards)
26+
- Cross-chain token swaps across 90+ blockchains
27+
- Display product information (title, description, image)
28+
- Customizable UI with dark and light mode support
29+
- Display fiat values in multiple currencies
30+
31+
## Get Started
32+
33+
You can integrate the buy widget into your website using an iframe or a React component.
34+
35+
<div className="space-y-4">
36+
37+
<ArticleIconCard
38+
title="Iframe"
39+
icon={FrameIcon}
40+
description="Integrate buy widget into your website using an iframe"
41+
href="/bridge/buy-widget/iframe"
42+
/>
43+
44+
<ArticleIconCard
45+
title="React Component"
46+
icon={ReactIcon}
47+
description="Integrate buy widget into your app using a React component"
48+
href="/bridge/buy-widget/react"
49+
/>
50+
51+
</div>
52+
53+
## Try it out
54+
55+
<ArticleIconCard
56+
title="Buy Widget Playground"
57+
description="Try out the Buy Widget in our live playground"
58+
icon={PlayIcon}
59+
href="https://playground.thirdweb.com/bridge/buy-widget"
60+
/>
61+

‎apps/portal/src/app/bridge/buy-widget/react/page.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
import {
2+
ArticleIconCard,
3+
createMetadata,
4+
} from "@doc";
5+
import { PlayIcon } from "lucide-react";
6+
import { ReactIcon } from "@/icons";
7+
8+
export const metadata = createMetadata({
9+
image: {
10+
title: "Buy widget component",
11+
icon: "payments",
12+
},
13+
title: "Buy widget component",
14+
description: "Add a widget to let users buy crypto in your app using a React component",
15+
});
16+
17+
# Buy widget component
18+
19+
The Buy widget component makes it easy for users to purchase crypto tokens in your app
20+
21+
## Features
22+
23+
- Purchase crypto tokens with fiat (credit/debit cards)
24+
- Cross-chain token swaps across 90+ blockchains
25+
- Display product information (title, description, image)
26+
- Customizable UI with dark and light mode support
27+
- Display fiat values in multiple currencies
28+
29+
## Example
30+
31+
You will need a thirdweb project client id to use the `BuyWidget` component. You can get your clientId by creating a project in the [thirdweb dashboard](https://thirdweb.com/team).
32+
33+
```tsx
34+
import { BuyWidget } from "thirdweb/react";
35+
import { createThirdwebClient } from "thirdweb";
36+
import { base } from "thirdweb/chains";
37+
38+
const client = createThirdwebClient({
39+
clientId: "YOUR_THIRDWEB_CLIENT_ID",
40+
});
41+
42+
function Example() {
43+
return (
44+
<BuyWidget
45+
client={client}
46+
chain={base}
47+
amount="0.01"
48+
/>
49+
);
50+
}
51+
```
52+
53+
Make sure to wrap the component containing `BuyWidget` with the `ThirdwebProvider` component.
54+
55+
```tsx
56+
import { ThirdwebProvider } from "thirdweb/react";
57+
58+
function App() {
59+
return (
60+
<ThirdwebProvider>
61+
<YourApp />
62+
</ThirdwebProvider>
63+
);
64+
}
65+
```
66+
67+
### Prefill a specific token
68+
69+
You can prefill the widget with a specific token by passing the `tokenAddress` prop.
70+
71+
```tsx
72+
import { BuyWidget } from "thirdweb/react";
73+
import { base } from "thirdweb/chains";
74+
75+
function Example() {
76+
return (
77+
<BuyWidget
78+
client={client}
79+
chain={base}
80+
// USDC on Base
81+
tokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
82+
amount="10"
83+
/>
84+
);
85+
}
86+
```
87+
88+
### Send to a specific address
89+
90+
By default, the connected wallet address receives the purchased tokens.
91+
92+
You can set `receiverAddress` prop to send the purchased tokens to a different address.
93+
94+
```tsx
95+
import { BuyWidget } from "thirdweb/react";
96+
import { base } from "thirdweb/chains";
97+
98+
function Example() {
99+
return (
100+
<BuyWidget
101+
client={client}
102+
chain={base}
103+
amount="0.01"
104+
receiverAddress="0x123...abc"
105+
/>
106+
);
107+
}
108+
```
109+
110+
## API Reference
111+
112+
<ArticleIconCard
113+
title="BuyWidget Component"
114+
description="View the API reference for the BuyWidget component"
115+
icon={ReactIcon}
116+
href="/references/typescript/v5/BuyWidget"
117+
/>
118+
119+
## Try it out
120+
121+
<ArticleIconCard
122+
title="Buy Widget Playground"
123+
description="Try out the Buy Widget in our live playground"
124+
icon={PlayIcon}
125+
href="https://playground.thirdweb.com/bridge/buy-widget?tab=react"
126+
/>
127+

0 commit comments

Comments
 (0)