Browser SDK overview

The Givebear SDK is the embeddable browser script for adding donation and community widgets to any website. You load it from https://givebear.io/sdk/givebear.js, and it exposes a global named window.Givebear.

This page explains what the SDK is for and how its pieces fit together. To load it and call methods, see Installation and API.

Here is a widget the SDK renders, live. Every widget has a copy-paste snippet and a live example like this one in snippet examples.

What window.Givebear does

The script renders Givebear widgets in the host page and opens the hosted donation flow. The global exposes these methods:

• renderButton: mounts a donation button.
• renderCard: mounts a donation card.
• renderInline: mounts the donation form inline (also aliased as render).
• renderPrayerTimes: mounts a prayer-times widget.
• renderCalendar: mounts a calendar widget.
• renderThermometer: mounts a fundraising progress widget.
• renderCampaignHero: mounts a full campaign block with progress and a donate button.
• renderSupporters: mounts a ticker cycling anonymized recent gifts.
• renderEventCard: mounts one published event with a register button.
• open: opens the donation experience in a modal.
• unmount: tears down a mounted widget so its element can be reused.
• track: a no-op kept for backward compatibility (see below).
• version: the SDK version string (currently 2.1.0).

Each render method takes a target (a CSS selector or an Element) and a config object. Widgets render inside a shadow root, so the host page's CSS does not leak in or out.

The SDK also auto-mounts. On load it scans the DOM for elements carrying data-givebear-* attributes (data-givebear-button, data-givebear-card, data-givebear-embed, data-givebear-calendar, data-givebear-events, data-givebear-prayer-times, data-givebear-thermometer, data-givebear-campaign-hero, data-givebear-supporters, data-givebear-event-card) and mounts the matching widget once. This is what makes a paste-only embed work without any JavaScript. The full attribute list is in the configuration reference.

When to use the SDK

The SDK and the dashboard's copy-paste embeds share the same script. Choose based on how much control the page needs.

• Use a dashboard-generated embed when staff can paste a snippet and the widget should mount where it sits. This is the default and needs no code.
• Use the SDK methods when code decides where, when, or how a widget renders: mounting after data loads, opening a modal from a custom button, or reusing one config across many widgets.

The SDK renders widgets, but it does not set up payments. The organization must be able to accept payments in the dashboard first (Stripe Connect onboarding, funds, and campaigns). If the donation path is broken in the dashboard, the SDK cannot fix it.

App attribution with appId

Every config accepts an optional appId. This is a Givebear Connect app's client_id. When a connected app embeds a widget and passes its appId, donations collected through that widget are attributed to the app.

Under the hood the SDK forwards appId as the app query parameter on the hosted embed URL it opens (/embed/<organizationId>?app=<clientId>). The donation flow then records the app as the attribution source for that session.

You can set it two ways:

• Programmatically, as appId in the config you pass to a render method or open.
• Declaratively, with the data-app-id attribute on an auto-mounted element.

If you are not building a Connect app, leave appId unset. To learn how Connect apps are registered and authenticated, start with the Connect overview and quickstart.

For stronger control, Connect platforms can mint an embed session on their backend and pass its token as sessionToken. The session pins the org, the fund or campaign, amounts, donor prefill, and attribution server-side, so the host page cannot change them. See Embedded donations.

How the SDK loads

The script is served from /sdk/givebear.js with permissive CORS so it loads on any domain. It is cached for one hour. The recommended loader uses a small async stub that queues your callbacks and runs them once the bundle arrives, so your code never races the download. The loader and call patterns are covered in Installation and API.

Where to go next