Guide · Next.js

App Router

Add a campaign widget and entitlement gates to a Next.js app.

Start with a public campaign and no credentials. Add customer identity and entitlement gates when your product is ready for them.

Start with only the campaign

A published campaign can be embedded without a developer project, API keys, or changes to your authentication.

Terminal
pnpm add @our-impact/browser
components/community-campaign.tsx
"use client";

import { useEffect, useRef } from "react";
import { mountCampaign } from "@our-impact/browser";

export function CommunityCampaign({ publicId }: { publicId: string }) {
  const target = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!target.current) return;

    const campaign = mountCampaign({
      target: target.current,
      publicId,
      height: "auto",
    });

    return () => campaign.destroy();
  }, [publicId]);

  return <div ref={target} />;
}

What you will build

Identified widget

The campaign knows which signed-in customer completed a donation.

Automatic evaluation

A verified PayPal capture becomes a project event and evaluates entitlement rules.

Product gate

The Next.js app checks a stable entitlement key before showing a benefit.

Configure Our Impact first

  1. 1
    Create or select a workspace

    The workspace owns both the community campaigns and developer projects used by your application.

  2. 2
    Add recipient organizations

    Invite each recipient to connect its own PayPal account, then wait until it is ready to receive.

  3. 3
    Publish a campaign

    Choose its recipients, schedule, voting behavior, and commitment. Copy the public embed URL.

  4. 4
    Create a developer project

    Add your Next.js origin, then copy the publishable key and the one-time server secret.

  5. 5
    Create an entitlement

    Give it a stable key such as community_champion and add an earning path such as “lifetime donations of at least $50.”

Connect the Next.js application

1

Install both SDKs

Terminal
pnpm add @our-impact/node @our-impact/browser
2

Add project 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-campaign-id
3

Create one server-only client

lib/our-impact/server.ts
import "server-only";
import { OurImpactClient } from "@our-impact/node";

export const ourImpact = new OurImpactClient({
  secretApiKey: process.env.OUR_IMPACT_SECRET_KEY,
});
4

Issue identity after authenticating the customer

This Server Component uses the application’s existing session. The stable application user ID becomes the supporter ID inside this developer project.

app/community/page.tsx
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";
import { ourImpact } from "@/lib/our-impact/server";
import { CommunityProgram } from "@/components/community-program";

export default async function CommunityPage() {
  const session = await auth();
  if (!session?.user?.id) redirect("/login");

  const identity = await ourImpact.identity.createIdentityToken({
    body: {
      externalUserId: session.user.id,
      displayName: session.user.name ?? undefined,
      ttlSeconds: 900,
    },
  });

  return (
    <CommunityProgram
      userToken={identity.token}
      publishableKey={process.env.NEXT_PUBLIC_OUR_IMPACT_PUBLISHABLE_KEY!}
      campaignId={process.env.NEXT_PUBLIC_OUR_IMPACT_CAMPAIGN_ID!}
    />
  );
}
5

Identify the widget and render a client-side gate

The same short-lived token powers both the hosted campaign and browser entitlement reads. The SDK creates the iframe, identifies the supporter, removes nested scrolling, and refreshes entitlements after a completed donation.

components/community-program.tsx
"use client";

import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { OurImpact } from "@our-impact/browser";

export function CommunityProgram({
  userToken,
  publishableKey,
  campaignId,
}: {
  userToken: string;
  publishableKey: string;
  campaignId: string;
}) {
  const campaignTarget = useRef<HTMLDivElement>(null);
  const [isChampion, setIsChampion] = useState(false);
  const impact = useMemo(
    () => new OurImpact({ publishableKey, userToken }),
    [publishableKey, userToken],
  );

  const refreshAccess = useCallback(async () => {
    await impact.refresh();
    setIsChampion(await impact.user.is("community_champion"));
  }, [impact]);

  useEffect(() => { void refreshAccess(); }, [refreshAccess]);

  useEffect(() => {
    if (!campaignTarget.current) return;
    const widget = impact.widgets.mountCampaign({
      target: campaignTarget.current,
      publicId: campaignId,
      height: "auto",
      onDonationCompleted() {
        void impact.user.is("community_champion").then(setIsChampion);
      },
    });
    return () => widget.destroy();
  }, [campaignId, impact]);

  return (
    <main data-community-champion={isChampion || undefined}>
      <div ref={campaignTarget} />

      {isChampion ? <ChampionExperience /> : <StandardExperience />}
      <button onClick={() => void refreshAccess()}>Refresh benefits</button>
    </main>
  );
}
6

Protect a route on the server when needed

For authorization—not just visual personalization—query with the secret SDK before rendering or mutating protected data.

app/champion-area/page.tsx
const result = await ourImpact.entitlements.listUserEntitlements({
  externalUserId: session.user.id,
});

const canAccess = result.entitlements.some(
  (item) => item.entitlementKey === "community_champion"
    && item.state === "active",
);

if (!canAccess) redirect("/community");

What happens after a donation

PayPal capture completes inside the campaign widget. Our Impact records the donation against the campaign and recipient, then creates donation.completed for the identified supporter in this developer project.

The project evaluates every matching entitlement rule. A subsequent browser impact.refresh(), server render, or server entitlement query returns the new state.