Fastify

This guide shows how to add Zero Ad Network to an existing Fastify application. If you haven't installed the package yet, start with the Node.js setup guide.

Add the plugin

Register a Fastify plugin that injects the partner header and attaches tokenContext to every request:

src/plugins/zeroad.ts

import fp from "fastify-plugin"
import { Site, FEATURE } from "@zeroad.network/token"

const site = Site({
  clientId: "YOUR_CLIENT_ID", // from zeroad.network/publisher/sites
  features: [FEATURE.CLEAN_WEB], // or FEATURE.ONE_PASS, or both
})

// Extend FastifyRequest so TypeScript knows about tokenContext
declare module "fastify" {
  interface FastifyRequest {
    tokenContext: ReturnType<typeof site.parseClientToken>
  }
}

export default fp(async (app) => {
  app.addHook("onRequest", async (request, reply) => {
    reply.header(site.SERVER_HEADER_NAME, site.SERVER_HEADER_VALUE)
    request.tokenContext = site.parseClientToken(request.headers[site.CLIENT_HEADER_NAME])
  })
})

src/app.ts

import Fastify from "fastify"
import zeroad from "./plugins/zeroad.js"

const app = Fastify()
await app.register(zeroad)

Use the feature flags

request.tokenContext is available in every route handler. Use the flags to tailor the response - non-subscribers get false for all flags and see the site as normal.

app.get("/article/:slug", async (request) => {
  const article = await db.getArticle(request.params.slug)
  const { DISABLE_CONTENT_PAYWALL, HIDE_ADVERTISEMENTS } = request.tokenContext

  return {
    title: article.title,
    content: DISABLE_CONTENT_PAYWALL ? article.fullContent : article.excerpt,
    isPaywalled: !DISABLE_CONTENT_PAYWALL,
    showAds: !HIDE_ADVERTISEMENTS,
  }
})

Full working example

A minimal Fastify app with the integration wired up end-to-end:

src/app.ts

import Fastify from "fastify"
import { Site, FEATURE } from "@zeroad.network/token"

const site = Site({
  clientId: "YOUR_CLIENT_ID",
  features: [FEATURE.CLEAN_WEB, FEATURE.ONE_PASS],
})

declare module "fastify" {
  interface FastifyRequest {
    tokenContext: ReturnType<typeof site.parseClientToken>
  }
}

const app = Fastify()

app.addHook("onRequest", async (request, reply) => {
  reply.header(site.SERVER_HEADER_NAME, site.SERVER_HEADER_VALUE)
  request.tokenContext = site.parseClientToken(request.headers[site.CLIENT_HEADER_NAME])
})

app.get("/", async (request) => {
  const { HIDE_ADVERTISEMENTS, DISABLE_CONTENT_PAYWALL } = request.tokenContext
  return { HIDE_ADVERTISEMENTS, DISABLE_CONTENT_PAYWALL }
})

await app.listen({ port: 3000 })

Full runnable examples for Fastify and other frameworks are in the GitHub examples directory.

What the flags mean

See the tokenContext reference for the full flag list and when each one is true.