Quickstart
Next.js · 20 minutesGo from a normal website to an identified campaign experience.
This path mirrors the reference paper storefront: baseline application, public campaign widget, then user identity and entitlement checks.
Prerequisites
Phase one — mount the campaign
A public campaign can be embedded before you integrate customer identity or entitlement logic.
Install the browser package
pnpm add @our-impact/browserMount the published campaign
Use the public campaign ID—not its database UUID. The SDK creates and resizes the hosted iframe and validates messages from the Our Impact origin.
"use client";
import { mountCampaign } from "@our-impact/browser";
import { useEffect, useRef } from "react";
export function CommunityCampaign({ publicId }: { publicId: string }) {
const target = useRef<HTMLDivElement>(null);
useEffect(() => {
if (!target.current) return;
const widget = mountCampaign({
target: target.current,
publicId,
height: "auto",
});
return () => widget.destroy();
}, [publicId]);
return <div ref={target} />;
}Render it anywhere in the existing product
Your application keeps its own navigation, account system, and visual design. The widget only owns the campaign frame.
Phase two — identify the supporter
Add the server SDK only when campaign activity should accumulate toward project entitlements for a signed-in customer.
Install the trusted server package
pnpm add @our-impact/nodeStore the project and campaign configuration
OUR_IMPACT_SECRET_KEY=oi_sk_test_...
NEXT_PUBLIC_OUR_IMPACT_PUBLISHABLE_KEY=oi_pk_test_...
NEXT_PUBLIC_OUR_IMPACT_CAMPAIGN_ID=your-public-campaign-idIssue identity from an authenticated server route
Use the stable ID from your existing session. Do not accept an arbitrary external user ID from browser input.
import { OurImpactClient } from "@our-impact/node";
import { getCurrentUser } from "@/lib/session";
const impact = new OurImpactClient({
secretApiKey: process.env.OUR_IMPACT_SECRET_KEY,
});
export async function GET() {
const user = await getCurrentUser();
if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });
const identity = await impact.identity.createIdentityToken({
body: {
externalUserId: user.id,
displayName: user.name,
ttlSeconds: 900,
},
});
return Response.json(
{ token: identity.token, expiresAt: identity.expiresAt },
{ headers: { "Cache-Control": "private, no-store" } },
);
}Share identity between the widget and entitlement checks
An identified widget attributes a verified donation to the project that issued the token. The same browser client can then read the resulting entitlement state.
const impact = new OurImpact({
publishableKey,
userToken: identityToken,
});
const isChampion = await impact.user.is("community_champion");
const widget = impact.widgets.mountCampaign({
target: "#community-campaign",
publicId: campaignId,
height: "auto",
onDonationCompleted() {
void impact.refresh();
},
});Verify the integration
- 1The campaign renders without a signed-in customer.
- 2A signed-in customer receives a short-lived identity token.
- 3The identified widget reports an identified status.
- 4A completed sandbox donation appears in the developer project.
- 5The matching entitlement changes to active when its rule qualifies.
- 6Signing out clears the identity and cached entitlement state.
Reference implementation
Baseline → campaign widget
Review the exact package, component, page, and styling changes from phase one.
Open comparisonWidget → identified entitlements
Review the server identity route, provider, entitlement check, and reward experience.
Open comparisonNeed the framework-specific version? Continue to the complete Next.js guide.
