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.sandbox.charitips.com.
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',
});<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>The documentation can be found here.
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;
// Hide search bar with filters
hideSearch?: 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;
}