Skip to content
kanca
NewStorefront script monitoring

Know when your ikas app fails a store.

Webhook deliveries, Admin API calls, installs, admin vitals and storefront script errors, per store. A few lines of code, no ikas credentials.

Start for free
npm i @kanca-app/ikas
kanca.onurhan.dev/projects/rush
Kanca Overview for an app named rush over the last 7 days: 56 active installs with 5 whose access was revoked, 96% webhook success, 1.2% Admin API errors and an LCP p75 of 2.84 s, above charts of install and uninstall events per day.
The Overview. Real dashboard, sample data.

What the ikas Partner dashboard does not show

It counts installs. Kanca shows what happens after one, per store and per operation.

Signals Kanca records and the problems each one surfaces
SignalWhat is measuredWhat it catches
WebhooksEvery delivery your app receives: scope, status, handler time, retries.A scope that started failing, and webhooks ikas stopped retrying.
Admin APIError rate and latency per GraphQL operation.A 200 response that carries an errors array, which most logs call a success.
InstallsInstalls, uninstalls found by a daily install check, and stores whose Admin API access was revoked.Stores leaving right after a release.
Admin performanceLCP, INP and CLS of your app inside the ikas admin iframe.A page that takes four seconds to paint for merchants.
Storefront scriptErrors thrown by your script on merchants' storefronts, and what it costs visitors to load.A release that throws on some themes, before a merchant writes to you.
StoresEach store using your app, ranked by failures, with its last error.The one store whose token expired while every other store is fine.
kanca — Turkish for hookCaspar David Friedrich, The Monk by the Sea, 1810

Answers per store, not just totals

A total hides the one store that is broken. Each view starts from the store.

01Stores

The one store whose token expired, while every other store is fine.

A page per store: status, install history and a timeline of everything it sent.

02Admin performance

No verdict until 100 samples.

Pass or needs work per admin page over 28 days; before that it says “not enough data”.

03Storefront script

Errors from your script only, never the theme’s.

Plus what it costs visitors to load. Under 3 KB gzipped.

Why a delivery failed, and which ones ikas gave up on

ikas retries anything but HTTP 200. Kanca groups failures by scope and reason.

HANDLER_THREW
Your handler threw
NO_RESPONSE
It resolved without a Response
HTTP_<status>
It returned another status
Lost
Every attempt failed, the last over an hour ago
Webhook failure reasons on the Overview: store/order/created and store/order/updated fail with HANDLER_THREW (Error: connect ECONNREFUSED) and HTTP_503, each with a failure count and last seen time.
Failures seen by your app. Deliveries that never arrived are invisible to the SDK.

An alert when a rule starts failing, and one when it recovers

Checked every minute, posted to Slack or Discord on the transition. Counts and a link, never event data.

Alert rules
RuleFires when
Admin API error rate5% or higher over the last 15 min, with at least 20 calls
Webhook failure rate5% or higher over the last 15 min, with at least 10 deliveries
Lost webhooksAny webhook that ikas stopped retrying (every delivery failed, last one over 1 hour ago), checked over the last 15 min
Storefront script errors5% or more of storefront page views with a script error over the last 15 min, with at least 20 sampled page views
Install check stoppedNo install check (checkInstalls run) for over 36 hours, after at least one was received
Daily event limitAccepted events reach the daily quota: 10,000 a UTC day for unverified projects, 1,000,000 for verified ones

Two keys, one ingest

Your server sends with the server key, browsers with the public key. Kanca validates every event and computes the dashboard from raw rows.

Your app server

Webhooks, installs, Admin API calls

Browsers

Admin iframe vitals, storefront script

kk_ server key
kp_ public key

Kanca ingest

Validated per event, deduplicated by event id, so a resent batch never counts twice

Dashboard and alerts

Computed from raw rows at query time, per store

The public key can only send vitals and storefront events, so it is safe to ship in a browser.

One line per part of your app

Each line covers one part of the ikas app starter. The SDK never throws and never changes a response; without a key it does nothing.

The whole integration
import { createKanca } from "@kanca-app/ikas";
export const kanca = createKanca({ key: process.env.KANCA_KEY });

// Webhook route
export const POST = kanca.webhook(handler);

// OAuth callback
kanca.track("install", { merchantId, storeName });

// Admin API client
return kanca.instrument(new ikasAdminGraphQLAPIClient(options));

// Daily job: records stores that removed the app
await kanca.checkInstalls(stores);

// Admin layout
<KancaVitals publicKey={process.env.NEXT_PUBLIC_KANCA_PUBLIC_KEY} />

Metadata in, nothing else

Everything else is dropped before it leaves your server or the browser. No ikas client secret. Events are kept until you ask us to delete them.

Recorded

  • Event type and name (scope, operation, metric)
  • Status, duration, error code and a short message
  • Merchant id, store name, webhook delivery id
  • Storefront: host, path pattern, script name and release

Never sent

  • Webhook payloads or signatures
  • GraphQL queries, variables or responses
  • Headers, access tokens, query strings
  • Customer, cart or order data, cookies, storage

See your first event in five minutes.

Create a project, copy two keys, and the setup page ticks off each line of the integration as its first event arrives.

Start for free
npm i @kanca-app/ikas