<div align="center">
	<a href="https://chainvine.xyz">
		<img  width="500" src="https://d3siz8o25n067q.cloudfront.net/png/lockup-black-w-clearspace.png" alt="ChainVine" style="filter: brightness(0%);" />
	</a>
</div>

<h3  align="center">@chainvine/widget</h3>
<div  align="center">

![status](https://img.shields.io/badge/status-active-success.svg)
![npm](https://badge.fury.io/js/%40chainvine%2Fwidget.svg)
![npm bundle size](https://img.badgesize.io/https:/unpkg.com/browse/@chainvine/widget/dist/esm/index.js?compression=gzip&label=bundle%20size)
![npm](https://img.shields.io/npm/dt/@chainvine/widget)

</div>

## Table of Contents

* [About](#about)

* [Getting Started](#getting-started)

* [Usage](#usage)

* [Support](#support)
# 🔍 About

Chainvine Widget is an embeddable widget UI that allows you to display referral and reward data to your users on your website. Its built against ChainVine's all-in-one solution for Referral & Affiliate marketing.

The widget allows you to get started quickly. Avoids having to invest the front-end work required to do so.

Simply add widget to your website and if needed customize the experience by interacting with our [SDK](https://socket.dev/npm/package/@chainvine/sdk) to capture referral links, retrieve rewards, fetch completed objectives, etc.

# 🚀 Getting Started <a name = "getting_started"></a>

## Features

* Supports CommonJS AND ESM, therefore browsers and node environments with modern bundlers
* Depends on React but excludes react and read-dom dependencies
* Supports client-side and server-side rendering (like NextJS)
* Includes Typescript definition files

## Requirements

* Node: v16.18.1
* React: v18+

## Installation

```bash
npm  install  @chainvine/widget
```

## Documentation

For more details, refer to our [documentation](https://docs.chainvine.com/technical/) amongst:
* [Details about the Product and Features](https://docs.chainvine.xyz/chainvine/product-and-features)
* [Embedding the widget](https://docs.chainvine.xyz/developers/embedded-widget)
* [Interacting with the SDK](https://docs.chainvine.xyz/developers/sdk)
* [Receiving Webhook events](https://docs.chainvine.xyz/developers/webhooks)
* [Advanced guidelines / Use cases](https://docs.chainvine.xyz/developers/use-cases)

## Usage

We support different use cases: client-side, server-side and through our SDK. Using either API key or allow-listed domain.

* Example 1) [Embedded in React with API key (client-side)](https://docs.chainvine.xyz/developers/sdk/classes-and-functions/chainvineuser/initializing-the-client)

* Example 2) [Embedded in NextJS/React (server-side)](https://codesandbox.io/p/sandbox/c-4vsxr7?embed=1&file=%2Fapp%2Fpage.tsx%3A21%2C28)

* Example 3) [Interacting with SDK](https://docs.chainvine.xyz/developers/sdk/implementation)

* Example 4) Embedded in React with Allow-listed domain (client-side)

```typescript jsx
import React, { useState } from "react";
import { ChainvineWidget } from "@chainvine/widget";

// 📌 Adapt the following accordingly...
//
// 1️⃣ The wallet address of the user
const walletAddress = '0x1234567890'; 
//
// 2️⃣ The campaign id you created in your community at https://chainvine.xyz
const campaignId = 'ABC123';
//
// 3️⃣ Add your domain to white-list (https://docs.chainvine.xyz/developers/sdk/classes-and-functions/authentication/allow-listing-a-domain)

export const ChainvineWidgetAndButton = () => {
  const [isOpen, setIsOpen] = useState<boolean>(true);

  return (
    <ChainvineWidget
      isOpen={isOpen}
      userWalletAddress={walletAddress}
      campaignId={campaignId}
      clientConfig={{
        testMode: true,
        logToConsole: true,
      }}
      onClose={() => setIsOpen(false)}
    >
      <button
        type={"submit"}
        onClick={() => {
          setIsOpen(true);
        }}
      >
        Open Widget
      </button>
    </ChainvineWidget>
  );
};
```

## Authorization

We proposed two methods of interacting with the ChainVine Widget: API Key or by omitting the API key and ensuring all requests are sent from a previously allow-listed domains.

It is advised to use the API key method as it is more secure and allows you to use Widget from any domain, but only if you are operating from a server context (i.e. from an API, or SSR framework such as NextJS) as you do not want to expose your API key in a browser.

# Support

If you have any questions or need support, feel free to reach out to us at

[<img height=20 src="https://assets.website-files.com/6463b21c61433a34bcb3370e/646511404eb94d91540204bb_Twitter.svg" />](https://twitter.com/chainvine_xyz)
[<img height=20 src="https://assets.website-files.com/6463b21c61433a34bcb3370e/64651140d7af390cc70c4ba2_Telegram-2.svg" />](https://t.me/chainvinehq)
