@charitips/embed

This library allows you to integrate our charities selection widget into your website.

For more instructions on how to use the Charitips API, checkout the developers documentation at https://developers.charitips.com.

Embed as a widget via JavaScript

yarn add @charitips/embed

import { createWidget } from '@charitips/embed';

createWidget({
  baseUrl: 'https://embed.charitips.com', // https://embed.sandbox.charitips.com for the sandbox environment
  container: document.querySelector('#<parent-container-id>'),
  publicKey: '<your-campaign-public-key>',
  type: 'presentation',
});

Embed via HTML

<div id="<parent-container-id>"></div>
<script>
  (function (d, t) {
    var g = d.createElement(t),
      s = d.getElementsByTagName(t)[0];
    g.src = 'https://unpkg.com/@charitips/embed';
    s.parentNode.insertBefore(g, s);
    g.onload = function () {
      window.charitips.createWidget({
        baseUrl: 'https://embed.charitips.com', // https://embed.sandbox.charitips.com for the sandbox environment
        container: document.querySelector('#<parent-container-id>'),
        publicKey: '<your-campaign-public-key>',
        type: 'presentation',
      });
    };
  })(document, 'script');
</script>

Documentation

The documentation can be found here.

Configuration

The createWidget function accept the following configuration:

interface CreateWidgetOptions {
  // https://embed.sandbox.charitips.com for the sandbox environment / https://embed.charitips.com for the production environment
  baseUrl: string;
  // Id of the parent container in which the widget will be displayed. The widget will fit its parent size.
  container: HTMLElement;
  // Optional id to allow several widgets on the same page
  id?: string;
  // Public key of the campaign. Can be found in the dashboard in the campaign's info tab
  publicKey: string;
  // In presentation mode, the charities are displayed but the donation can't be claimed. This is useful if you need to display the list of charities before recording a donation.
  // In charity_and_amount_selection mode, onCharitySelected is required. Allows the user to pick a charity and an amount. This is the recommended flow.
  // In charity_selection mode, amount and onCharitySelected are required. Allows the user to pick a charity if the amount is known beforehand.
  // In charity_preselection mode, onCharityPreselected is required. Allows the user to choose a charity beforehand without creating a donation right away. For example, if you want your user to select a charity in their profile settings and save this information for later.
  // In claim mode, the user can claim its donation. One of donationSecret or voteSecret is required. The donation has to be created beforehand.
  type?: 'presentation' | 'charity_and_amount_selection' | 'charity_selection' | 'charity_preselection' | 'claim';
  // Used in charity_and_amount_selection mode as the max amount allowed. If no currency is provided, amount should be in euros.
  balance?: number;
  // Used in charity_and_amount_selection mode as the way to specify any custom currency used in your app such as credits, points, tokens etc. Default value is €.
  currencySymbol?: string;
  // Used in charity_and_amount_selection mode. Allows to convert your custom currency in euros. This should be the amount of points/credit/tokens equivalent to 1 €. Default value is 1.
  currencyValue?: number;
  // Amount in minor currency unit i.e cents. Should be an integer. Only used if neither donationSecret or voteSecret are used. This amount is displayed in the widget and allows to display what the charity will be able to do with this donation
  amount?: number;
  // Function called on charity selection for both charity_selection and charity_and_amount_selection mode. This function should call your back-end to create and claim a donation using our API. It should return a Promise resolving with the created donation.
  onCharitySelected?: (payload: { charityId: string; amount?: number }) => Promise<{
    donationId?: string;
    voteId?: string;
    recurrringDonationId?: string;
  }>;
  // Function called when a charity is selected by the user in charity_preselection mode. The widget UI is updated to reflect that the charity has been selected.
  onCharityPreselected?: (payload: { charityId: string }) => void;
  // Optional function called once a donation has been claimed. Can be useful to update your UI or redirect to a success/thank you screen.
  onDonationClaimed?: (payload: { charityId: string }) => void;
  // The secret property of the donation which should be claimed in claim mode (for FACE_VALUE campaigns i.e default campaigns)
  donationSecret?: string;
  // The secret property of the vote which should be casted in claim mode (for DISTRUBITION campaigns)
  voteSecret?: string;
  // Display the sustainable development goals filter
  withFilters?: boolean;
  // Display the how to instructions
  withInstructions?: boolean;
  // Display the campaign's title and description
  withDescription?: boolean;
  // Display the "See charities" CTA
  withDiscoverButton?: boolean;
  // Whether the widget should fill its container (default) or expand so that all its content fits into the page
  size?: 'fillContainer' | 'fitContent';
  // The layout of the widget. Default to grid
  layout?: 'grid' | 'row';
  // The locale to be used for the widget localization. Default to fr
  locale?: 'fr' | 'en';
  /*
    Prevent the success modal to be shown once the charity has been chosed. It means that you're responsible to redirect the user to the next step.
    The loading indicator on the CTA will spin indefinitely.
  */
  disableSuccessModal?: boolean;
  // Optional link to your terms of service if you wish to display a checkbox to accept them when choosing a charity
  termsOfServiceLink?: string;
  // Optional link to your terms of sales if you wish to display a checkbox to accept them when choosing a charity
  termsOfSalesLink?: string;
  // Optional link to your privacy policy if you wish to display a checkbox to accept them when choosing a charity
  privacyPolicyLink?: string;
  // Optional charityId to indicate the charity initially preselected in charity_preselection mode
  preselectedCharityId?: string;
}