Skip to content

Web

Install

npm install @heysada/nida

Banners, popups and the shopping-app formats for a web app: splash, stories, carousel, countdown, coupon, lucky draw (wheel or scratch card), floating button, social-proof toast and daily check-in. Every message is drawn from the app’s design, so a new campaign needs no release of the page.

Use it

import { configure, identify, mount, event, setConsent } from "@heysada/nida";

await configure({
  appKey: "ipk_…",                     // the panel → Keys
  apiUrl: "https://…",                 // where the service serves /sdk/v1
  placements: ["home_top", "home_popup"],
  onOpenUrl: (url) => router.push(url), // a call to action's link: the page opens it
});
await identify(user.id, user.hash);     // nothing is decided until someone is identified
await setConsent("in_app", true);       // with profilesUrl and profilesKey (Settings → Profile keys); strict

mount("home_top", document.querySelector("#home-top")!); // a banner, or nothing
mount("home_stories", document.querySelector("#stories")!); // a stories placement: its row
await event("add_to_cart");             // messages set to show when this happens

Popups, splashes, stories, floating buttons and toasts show over the page on their own, one presented message at a time. Pass presentPopups: false to draw them yourself from messages() and subscribe().

What it does

  • One decide per session for every placement (at most 10). A message shows once every picture it shows has loaded. event and screen ask for the messages set to them and add them; what the session shows stays.
  • Formats. A popup is a centre dialog, a bottom sheet or a full page, closed after close_after_seconds when it has one, and by a click outside unless dismiss_outside is off. A splash fills the page; its skip shows after skip_after_seconds and it closes by itself after duration_seconds. A stories placement (its Shown at once, max_shown, above 1) is a row of rings: mount draws it. A floating button sits at its position and moves where the user drags it. A toast shows for a few seconds, once a session.
  • A stories row. Every live story of the placement comes in one decide, best first. A story the user hasn’t seen has a gradient ring (the design’s stories_row look, through --r-stories_row-* custom properties), a seen one is grey and moves to the end; what was seen is kept in the browser per user. In Arabic the row starts at the right. A ring opens a modal viewer: progress bars, each page for its time (a video page for its length), a tap on either side to move, a held pointer to pause, a drag sideways to the next or previous story (mirrored in Arabic), a drag down or Escape to close, and focus back on the ring after. A story reports its impression when it opens, not when its ring draws.
  • The server decides. A coupon’s code, a draw’s prize and a check-in’s streak come from the service: the SDK only asks, then draws the view the service sends back with the result.
  • Reports. Impressions, clicks, dismissals, a story’s or carousel’s page views and conversions (reportConversion) are queued in the browser and sent in batches; a page left offline sends them later.
  • Push. setPushToken(token) registers the browser’s FCM web push token for the identified user, again after a sign-in; clearPushToken() on sign-out. handlePush(data) reports an opened push as a click and calls onPushOpened.
  • A strict Content-Security-Policy works: styles go through constructable style sheets, and a dragged button moves through CSSOM, never a style attribute.

Develop

npm ci
./check.sh        # wire drift, lint, types, tests, build, the locked public API
npm run gen       # src/wire.ts from the public API
npm run api       # writes etc/nida.api.md after a reviewed change to the public surface