@captaincause/dift-widget

v1.1.3

Published

2 days ago

This package is the home of the Dift widget, a lightweight version of our donation flow (accessible at https://dift.com/give?token=xxxx).

Downloads

336

0High
0Medium
0Low

tthsympa

natoromano

Dift's give flow widget

This package is the home of the Dift widget, a lightweight version of our donation flow (accessible at https://dift.com/give?token=xxxx).

The widget is composed a JavaScript file that handle the iframe, flow initialization and callbacks

How to use it

First, add the script throught a CDN.
```
<script
  async
  src="https://cdn.jsdelivr.net/npm/@captaincause/dift-widget/dist/dift-widget.min.js"
/>
```
While we recommend to use the latest version of the script, you can pin it for security reasons. See the NPM page of the package to find the latest version.
Add a div element on your page in which widget will be injected.
```
<div id="dift-widget" />
```

Initialize the widget. See below for more options.

const container = document.querySelector('#dift-widget')

const widget = new window.DiftWidget({
  container,
  token: 'aaa345bbbb872a2',
})

You should see the widget displayed in your page!

You can find below code examples of how to integrate the widget on your page.

Options

| Field | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | container | yes | The element in which the widget will be injected. You need to pass a valid DOM element, not an id. | | token | yes | The token of your Dift's campaign. You should be able to find it in Dift administration console. | | locale | no | Default to fr. Available locale are fr and en. | | onDonateSuccess | no | The callback is called when the donation flow is a success. An object will be passed to the callback. See below for more information. | | onDonateError | no | The callback is called when the donation flow fails. An object will be passed to the callback. See below for more information. | | onProjectSelection | no | The callback is called when a project is selected. An object is passed to the callback. See below for more information. | | onLoad | no | The callback is called when the widget is loaded. |

The onDonateSuccess will be called with the following objet passed as the function argument:

{
  // Uniq ID for the donation
  id: string

  // The amount of the donation user made.
  // `amount.amount` is representing cents.
  amount: {
    amount: number
    currency: 'EUR'
  }

  // Informations about the selected project.
  project: {
    id: string
    name: string
    url: string
  }
}

The onDonateError will be called with the following object passed as the function argument:

{
  // The error returned.
  error: {
    code: string
    message: string
  }

  // Informations about the selected project.
  project: {
    id: string
    name: string
    url: string
  }
}

The onProjectSelection will be called with the following ogject passed as the function argument:

{
  // Uniq ID project the project
  id: string
}

Instance methods

| Method | Description | | ------- | ----------------------------- | | destroy | Remove widget from your page. |

Code examples

Vanilla Javascript

<html>
  <head>
    <script type="text/javascript">
      function initializeDiftWidget() {
        new window.DiftWidget({
          container: document.getElementById('root'),
          token: 'd94658cd64e186c82887cc4f1a847b62',
        })
      }
    </script>
    <script
      src="https://cdn.jsdelivr.net/npm/@captaincause/dift-widget/dist/dift-widget.min.js"
      onload="initializeDiftWidget()"
      async
    ></script>
  </head>
  <body>
    <div id="root" />
  </body>
</html>

NextJS

Note: you can achieve the same in a pure React app by replacing the NextJS Script component by a classic script tag (inside a <head> tag)

import { useEffect, useRef } from 'react'
import Script from 'next/script'

function App() {
  const widgetRef = useRef(null)

  const onLoad = () => {
    widgetRef.current = new window.DiftWidget({
      container: document.querySelector('#widget'),
      token: 'aaa345bbbb872a2',
    })
  }

  useEffect(() => {
    const { current: widget } = widgetRef

    return () => {
      if (widget) {
        widget.destroy() // Don't forget to destroy it when your component unmount
      }
    }
  }, [])

  return (
    <>
      <Script
        src="https://cdn.jsdelivr.net/npm/@captaincause/dift-widget/dist/dift-widget.min.js"
        onLoad={onLoad}
      />

      <div id="widget" />
    </>
  )
}

The stack 🏗️

Node 18.x
Typescript
Javascript
Inline CSS
pnpm
eslint / prettier

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme