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

1. 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.

2. Add a div element on your page in which widget will be injected.

   <div id="dift-widget" />

3. 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. | | type | yes | Possibe values are small, original and impact. | | token | no | The token of your Dift's campaign. You should be able to find it in your Dift's administration console. Its required if you set small or original for field type | | organization | no | The slug of your organization on Dift. You should be able to find it in your Dift's administration console. Its required if you set impact for field type | | locale | no | Default to fr. Available locale are fr and en. | | impactMemberName | no | Optional field for "impact" widget. Specify your own way of calling people that participate on your Dift's campaigns. Prefer the plural form. "members" will be the term used by default. | | impactHideLogo | no | Optional field for "impact" widget. Hide or not the company logo. False by default. | | impactHeroTitle | no | Optional field for "impact" widget. Specify the title (h1) displayed on your impact widget. If not specified, a generic title will be provided by default. | | impactHeroDescription | no | Optional field for "impact" widget. Specify the description (below the title) on your impact widget. If not specified, a generic description will be provided by default. | | impactHideCumulatedImpact | no | Optional field for "impact" widget. Hide or not the section showing the cumulated impacts of all your campaigns. False by default. | | impactHideComments | no | Optional field for "impact" widget. Hide or not the section showing the comments of people partipating on your campaigns. False by default. | | impactHideNews | no | Optional field for "impact" widget. Hide or not the section showing the latest news of the associations you have funded with your campaigns. False by default. | | impactHideSeniority | no | Optional field for "impact" widget. Hide or not the seniority footer. False by default. | | 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 informations. | | onDonateError | no | The callback is called when the donation flow fails. An object will be passed to the callback. See below for more informations. | | onProjectSelection | no | The callback is called when a project is selected. An object is passed to the callback. See below for more informations. | | onLoad | no | The callback is called when the widget is loaded. |

The onDonateSuccess will be called with the following object 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 object passed as the function argument:

{
  // Uniq ID of a 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
• CSS
• pnpm
• eslint / prettier