@charitips/embed-react

This library allows you to integrate Charitips' widgets in your react web application.

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

You can find an integration example at https://github.com/charitips/demos.

More configuration options are available and can be found in the documentation.

Install

yarn add @charitips/embed-react

Setup

First, you'll need to add the CharitipsProvider to your app root :

import { CharitipsProvider } from '@charitips/embed-react';

export function App() {
  // your code...
  return (
    <CharitipsProvider
      baseUrl="https://embed.charitips.com" // https://embed.sandbox.charitips.com for the sandbox environment
    >
      {/* the rest of your providers */}
    </CharitipsProvider>
  )
}

Usage

Charitips offer two types of widgets:

• user widgets intended to be used by your end users and integrated in your application or website.
• admin widgets intended to be used by your b2b customers if revelant, by you or by your ops team. They can be integrated in your back office or in the admin dashboard you provide to your customers. Admin widgets require authentication. Learn more in the documentation

User widgets

• The CharitySelectionWidget to let a user choose which charity they wish to support

import { CharitySelectionWidget } from '@charitips/embed-react';

function CharitySelectionScreen({ publicKey }:{ publicKey: string }) {
  const onCharitySelected = useCallback(async ({ charityId, amount }) => {
    // Call your back-end to create a donation
    const { donationId } = await callBackEnd({ charityId, amount })
    return {
      donationId,
    };
  }, []);
  const onCloseSuccess = useCallback(() => {
    // Close screen
  }, []);
  return (
    <CharitySelectionWidget
      publicKey={publicKey}
      type="charity_and_amount_selection"
      size="fitContent"
      onCharitySelected={onCharitySelected}
      onCloseSuccess={onCloseSuccess}
    />
  );
}

• The B2CPaymentWidget to collect donations from your users

import { B2CPaymentWidget } from '@charitips/embed-react';

function DonationScreen({ charityId, publicKey }: { charityId:string; publicKey: string  }) {
  const onSuccess = useCallback((payload: {
    donationId: string,
    charityId: string,
    amount: number,
  }) => {
    // Callback triggered when the payment is successful
    // You can use this callback for example to link the created donation with your customer.
    // You can also linked the created donation & donor with your customer by updating the externalId/uniqueExternalId property on either the donation or the donor.
    // For other use cases, listening for the donation_create &  webhooks are recommended.
  }, []);
  return (
    <B2CPaymentWidget
      publicKey={publicKey}
      size="fitContent"
      charityId={charityId}
      onSuccess={onSuccess}
    />
  );
}

Admin widgets

• The AdminCharitiesSelectionWidget to let an admin configure the list of charities shown to the users for a given campaign

import { AdminCharitiesSelectionWidget } from '@charitips/embed-react';

function AdminScreen({ token, campaignId }: { token: string; campaignId: string }) {
  return (
    <AdminCharitiesSelectionWidget
      token={token}
      campaignId={campaignId}
      size="fitContent"
    />
  );
}

• The AdminCampaignMetricsWidget to monitor all metrics related to a given campaign

import { AdminCampaignMetricsWidget } from '@charitips/embed-react';

function AdminScreen({ token, campaignId }: { token: string; campaignId: string }) {
  return (
    <AdminCampaignMetricsWidget
      token={token}
      campaignId={campaignId}
      size="fitContent"
    />
  );
}

• The AdminGlobalMetricsWidget to monitor aggregated metrics across all campaigns

import { AdminCampaignMetricsWidget } from '@charitips/embed-react';

function AdminScreen({ token, campaignId }: { token: string; campaignId: string }) {
  return (
    <AdminGlobalMetricsWidget
      token={token}
      size="fitContent"
    />
  );
}

• The AdminFiscalReceiptsWidget to view and download generated fiscal receipts

import { AdminFiscalReceiptsWidget } from '@charitips/embed-react';

function AdminScreen({ token }: { token: string }) {
  return (
    <AdminFiscalReceiptsWidget
      token={token}
      size="fitContent"
    />
  );
}