Quickstart

Next.js · 20 minutes

Go 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.

1

Install the browser package

Terminal
pnpm add @our-impact/browser
2

Mount 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.

components/community-campaign.tsx
"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} />;
}
3

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.

1

Install the trusted server package

Terminal
pnpm add @our-impact/node
2

Store the project and campaign configuration

.env.local
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-id
3

Issue 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.

app/api/our-impact/identity/route.ts
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" } },
  );
}
4

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.

components/our-impact-provider.tsx
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

  1. 1The campaign renders without a signed-in customer.
  2. 2A signed-in customer receives a short-lived identity token.
  3. 3The identified widget reports an identified status.
  4. 4A completed sandbox donation appears in the developer project.
  5. 5The matching entitlement changes to active when its rule qualifies.
  6. 6Signing out clears the identity and cached entitlement state.

Reference implementation