---
name: integrate-notpixel
description: Set up or troubleshoot the NotPixel publisher SDK in an existing app, including real test ads, chat streaming and ad rendering.
---

# Integrate NotPixel

1. Find the app workspace, package manager, backend runtime, chat response path
   and existing NotPixel configuration. For an AI SDK chat, check the installed
   `ai` major before choosing the stream API.
2. Keep the supplied publisher ID and processing mode. If the ID is missing,
   get it from the publisher portal or ask the user. Install only the SDK for
   that app. With a publisher ID, direct setup requires no CLI login or LLM key
   for an ad-only check. Offer the interactive installer when the user needs
   help connecting their account.
3. A publisher test uses `testMode: true` (`test_mode=True` in Python) to fetch
   real ads from the NotPixel API. JavaScript support starts at `notpixel@4.2.0`.
   No fill is valid. A test ad has `testMode: true`, has no `impressionId` and must render with a
   disabled CTA and no tracking. Preserve the chosen local processing mode
   while troubleshooting.
4. Wire the configured client into the app's actual request path when the user
   asks to integrate it. Keep the existing model, tools and response format.
   Pass the ad separately from model text. If the app replaces streamed
   messages from a server snapshot or reloads them from storage, verify that the
   chosen message representation preserves the ad wherever it should appear.
5. Check the real lookup using the user's sample input. Then send a message in
   the running app and verify that a returned test ad appears with the test
   label and disabled CTA. If no card appears, report what you verified at each
   applicable stage from lookup through streaming, rendering and synchronization.
   A unit test with a synthetic ad verifies only that part of the integration.

## Read only the relevant guide

For JavaScript and TypeScript, open `node_modules/notpixel/dist/docs/index.md`
in the target workspace and follow the links for the integration you are working
on. These Markdown pages come from the public docs and ship with the installed
SDK version. In monorepos, locate the package as resolved by the app. If the
installed version predates bundled docs, check its README and public types
before using the latest web examples.

When installing the JavaScript SDK directly, add a NotPixel section to the app
workspace's `AGENTS.md` pointing to `node_modules/notpixel/SKILL.md` and the
bundled guide above. Preserve the app's instructions and update an existing
NotPixel section in place. The guided Node.js installer adds this section.

- [Installation and publisher setup](https://docs.notpixel.ai/getting-started/installation)
- [Real ad test mode](https://docs.notpixel.ai/features/test-mode)
- [Vercel AI SDK streaming](https://docs.notpixel.ai/integrations/ai-sdk)
- [Next.js and React rendering](https://docs.notpixel.ai/integrations/nextjs)
- [Python SDK](https://docs.notpixel.ai/python)
- [React Native SDK](https://docs.notpixel.ai/react-native)
- [Other documentation](https://docs.notpixel.ai/llms.txt)