diff --git a/mint.json b/mint.json index 58411aa..ff6dd28 100644 --- a/mint.json +++ b/mint.json @@ -179,16 +179,27 @@ "group": "Client SDKs", "icon": "js", "pages": [ - "sdks/client-side/introduction", { - "group": "Installation Guides", - "icon": "download", + "group": "Dub Analytics", + "icon": "circle-down", "pages": [ + "sdks/client-side/introduction", "sdks/client-side/installation-guides/react", "sdks/client-side/installation-guides/webflow", "sdks/client-side/installation-guides/wordpress", "sdks/client-side/installation-guides/framer" ] + }, + { + "group": "Dub Embed", + "icon": "circle-down", + "pages": [ + "sdks/embed-react/introduction", + "sdks/embed-react/react", + "sdks/embed-react/html", + "sdks/embed-react/link-public-token", + "sdks/embed-react/widget-customization" + ] } ] }, diff --git a/sdks/client-side/introduction.mdx b/sdks/client-side/introduction.mdx index f0490a1..84ca353 100644 --- a/sdks/client-side/introduction.mdx +++ b/sdks/client-side/introduction.mdx @@ -1,7 +1,6 @@ --- title: Introduction description: Client-side JavaScript SDK for for Dub Conversions -icon: code --- The following guides show you how to add [Dub Analytics](https://github.com/dubinc/analytics) to your website. diff --git a/sdks/embed-react/html.mdx b/sdks/embed-react/html.mdx new file mode 100644 index 0000000..c2e575e --- /dev/null +++ b/sdks/embed-react/html.mdx @@ -0,0 +1,62 @@ +--- +title: HTML +description: How to add Dub Embed to your HTML site +--- + +With Dub Embed, you can seamlessly integrate referral data visualization into your HTML site. + +## Quickstart + +This quick start guide will show you how to get started with Dub Embed on your HTML site. + + + + Add the script to your HTML file. + + ```html + + ``` + + + + + Initialize the widget by calling the `Dub.init` function and passing your link public token. + + ```html + + ``` + + This will initialize the widget and make it available on the `Dub` global object. + + + + + You can customize the widget by passing the props to the `Dub.init` function. + + For example, you can specify the placement of the widget or the trigger for the widget. + + ```html + + + // Open the widget on button click + + ``` + + For a full list of available props, please refer to the [widget customization](/sdks/embed-react/widget-customization) page. + + + diff --git a/sdks/embed-react/introduction.mdx b/sdks/embed-react/introduction.mdx new file mode 100644 index 0000000..d5cc4a7 --- /dev/null +++ b/sdks/embed-react/introduction.mdx @@ -0,0 +1,18 @@ +--- +title: Introduction +description: React SDK for embedding Dub in your React app +--- + +The following guides show you how to add [Dub Embed](https://github.com/dubinc/dub/tree/main/packages/embeds) to your React app. + +With Dub Embed, you can embed Dub widget in your React app and display the referral data for your users. + +[TODO: Add a screenshot] + +Based on the framework or platform you're using, you can install the script in different ways: + + + + Add Dub Embed to your React app or Next.js app. + + diff --git a/sdks/embed-react/link-public-token.mdx b/sdks/embed-react/link-public-token.mdx new file mode 100644 index 0000000..95196b6 --- /dev/null +++ b/sdks/embed-react/link-public-token.mdx @@ -0,0 +1,45 @@ +--- +title: Link Public Token +description: How to generate a link public token for your affiliate links +--- + +The link public token is a crucial component for securely embedding the Dub widget in your app. + +To generate a link public token, you must possess a **Workspace API key** that has the `links.write` scope. This scope grants the permission to generate tokens for links. + +The link public token is scoped to a specific link, meaning it can only be used in the context of that link. + +Additionally, for security purposes, the token is designed to expire after **2 hours**. This limited lifespan helps to minimize the risk of unauthorized access. + +It's important to implement a logic that listens for the token's expiration event so that a new token can be generated and used when the current one expires. + +The link for which you are generating a token must be part of an affiliate program otherwise the request to generate a token will not succeed. + +You can generate a link public token by using following methods: + + + +```bash curl +curl -X POST https://api.dub.co/tokens/embed \ + -H "Authorization: Bearer DUB_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"linkId": "LINK_ID"}' +``` + +```bash TypeScript +import { Dub } from "dub"; + +const dub = new Dub({ + token: "DUB_API_KEY", +}); + +const token = await dub.tokens.createEmbed({ + linkId: "LINK_ID", +}); +``` + + + +You should generate the token on the **server side** and pass it to the widget. Ideally you should create a new endpoint on your application that will generate the token and return it to the client based on the link ID. + +Ensure that the token is included in the widget's configuration to enable it to fetch and display the necessary data. diff --git a/sdks/embed-react/react.mdx b/sdks/embed-react/react.mdx new file mode 100644 index 0000000..ad3cf58 --- /dev/null +++ b/sdks/embed-react/react.mdx @@ -0,0 +1,73 @@ +--- +title: React +description: How to add Dub Embed to your React or Next.js site +--- + +With Dub Embed, you can seamlessly integrate referral data visualization into your React or Next.js application. + +## Quickstart + +This quick start guide will show you how to get started with Dub Embed on your app. + + + + Using the package manager of your choice, add the `@dub/embed-react` to your project. + + + + ```bash npm + npm install @embed-react + ``` + + ```bash pnpm + pnpm add @embed-react + ``` + + ```bash yarn + yarn add @embed-react + ``` + + ```bash bun + bun add @embed-react + ``` + + + + + + + You can use the `` component to embed the Dub widget in your React app. + + E.g. if you're using Next.js, you can add the `` component to your root layout component or any other pages where you want to embed the Dub widget. + + Follow the [link public token](/sdks/embed-react/link-public-token) guide to learn how to generate public token for your links. + + ```jsx app/layout.tsx + import { DubWidget } from "@dub/embed-react"; + + ; + ``` + + + + + You can customize the widget by passing the props to the `` component. + + For example, you can specify the placement of the widget or the trigger for the widget. + + ```jsx app/layout.tsx + import { DubWidget } from "@dub/embed-react"; + + ; + ``` + + For a full list of available props, please refer to the [widget customization](/sdks/embed-react/widget-customization) page. + + + diff --git a/sdks/embed-react/widget-customization.mdx b/sdks/embed-react/widget-customization.mdx new file mode 100644 index 0000000..90c8b70 --- /dev/null +++ b/sdks/embed-react/widget-customization.mdx @@ -0,0 +1,66 @@ +--- +title: Widget Customization +description: Learn how to customize the Dub widget +--- + +Dub Widget comes with a set of props that allow you to customize the widget looks and behavior. + +## Available props + + + The link public token. + + + + The trigger for the widget. Available options are `floating-button`, `manual`. + + + + The placement of the widget. Available options are `bottom-right`, + `bottom-left`, `top-right`, `top-left`, `center`. + + + + The callback function that is called when the widget is opened. + + + + The callback function that is called when the widget is closed. + + + + The callback function that is called when there is an error fetching the data. + + + + The callback function that is called when the link public token expires. + + + + The styles for the widget container. + + +The styles for the widget popup. + +The styles for the widget button. + +Here is a simple example of how to customize the widget: + +```tsx + console.log("Widget opened")} + onClose={() => console.log("Widget closed")} + onError={(error) => console.log("Error fetching data", error)} + onTokenExpired={() => console.log("Link public token expired")} + + // Styles + containerStyles={{ backgroundColor: "red" }} + popupStyles={{ backgroundColor: "blue" }} + buttonStyles={{ backgroundColor: "green" }} +/> +``` diff --git a/sdks/overview.mdx b/sdks/overview.mdx index ec6bed7..9263be5 100644 --- a/sdks/overview.mdx +++ b/sdks/overview.mdx @@ -35,4 +35,8 @@ icon: code Dub analytics SDK + + + Dub embed SDK +