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.
eventandscreenask 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_secondswhen it has one, and by a click outside unlessdismiss_outsideis off. A splash fills the page; its skip shows afterskip_after_secondsand it closes by itself afterduration_seconds. A stories placement (its Shown at once,max_shown, above 1) is a row of rings:mountdraws it. A floating button sits at itspositionand 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_rowlook, 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 callsonPushOpened. - A strict Content-Security-Policy works: styles go through constructable style sheets, and a
dragged button moves through CSSOM, never a
styleattribute.
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