Repository navigation
Releases
v1.4.0
Added
feishuconfig: charges, refunds and Apple's test notification also go to one person through a Feishu or Lark app bot, with the estimated proceeds and this month's totals. Free trial starts are not sent.base_urlmust behttps://; a trailing slash is dropped.appstore_events.offer_typeandoffer_identifier(migration v12): the offer each transaction used, from Apple'sofferTypeandofferIdentifier. Rows stored earlier have0and''.notification_deliveries(migration v13): transaction messages are queued per channel and sent by a background loop, so email and Feishu each retry on their own (after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h) and neither is sent twice because the other failed.
Changed
- The App Store notification endpoint answers 200 once the transaction and its messages are stored, and 500 only when they could not be stored. A failed email no longer makes Apple resend the notification. Without SMTP, transaction emails are no longer logged as skipped.
Fixed
- Only a subscription that starts at price 0 without an offer code counts as a free trial. A price-0 one-time purchase used to show as "Trial started" in the live feed, the Today view, reports and transaction emails; it is now counted as neither a trial nor a sale, and labeled "Code redeemed" (with the code's campaign name in the live feed) when an offer code was used, otherwise "Free".
v1.3.0
Changed
- The first charge after a free trial reads "Trial converted" instead of "Renewal" in the live feed, transaction emails and reports. Apple sends it as a plain
DID_RENEW, so a charge counts as a conversion when the same subscription has a stored free trial start and no earlier paid charge. - The Portfolio revenue mix labels renewals "Renewals (incl. trial conversions)", because App Store Connect sales reports do not separate the two.
v1.2.0
Added
- Metric
today: today so far across all apps from real-time sources (active users, new users, sessions, paywall viewers, errors, gross, sales, trials, refunds), each compared with yesterday up to the same time of day, with active users by hour and today's notifications. The Portfolio dashboard opens on a matching Today range (the default; Year moves to?range=year) that needs no app switching and refreshes every minute.
Changed
- The daily report no longer shows a day-over-day change for revenue (gross in the headline and per app, proceeds in the App Store table); DAU, new users, sessions and downloads keep theirs.
- Building the dashboard pins pnpm 10.18.3 through
packageManagerinweb/package.json. alerts.payment_errorsdefaults to[purchase, restore];products.loadno longer alerts on its first occurrence, because an empty load at first launch is usually transient. Users who really cannot buy still alert throughpurchase.failedwith reasonproduct_missing. Addproducts.loadback topayment_errorsto keep the old behavior.
Upgrade: replace the binary or image and restart. No database migration. If your config lists alerts.payment_errors explicitly, it is unchanged; otherwise products.load errors no longer alert on first occurrence.
v1.1.2
Fixed
- Dashboard on phones: the app, event and currency selects opened a menu that the horizontally scrolling filter bar clipped, so switching apps was impossible; the menu now opens fixed below its button. Column charts with up to 8 buckets (active days, days from install to purchase) show every label instead of dropping alternate ones.
Upgrade: replace the binary or image and restart. No database migration and no configuration change.
v1.1.1
Added
- Attribution for apps that pass their own stable
appAccountToken(an account ID) on every purchase, with HiwiKInsightKit 0.3.0'sbeginPurchase(product:context:appAccountToken:).purchase_attemptsnow keeps every attempt of a token (surrogate keyid, deduplicated by token, install and time), and the new viewv_attributionmaps each notification to one attempt: the latest attempt with the same token in the same app started no later than 5 minutes after the purchase (for renewals, refunds and expiry: after the purchase that started them). Thefunnelandrevenuemetrics, reports, transaction emails,is_paidandis_proall resolve through it. Tokens generated per purchase resolve exactly as before. appstore_eventsstoresapp,original_transaction_id,transaction_reason,purchase_atandoriginal_purchase_atfor new notifications.- Database migration v11 rebuilds
purchase_attempts(existing rows kept) and recreatesv_user_summary.
Upgrade: replace the binary or image and restart. Migration v11 rebuilds purchase_attempts (rows kept) and adds columns to appstore_events; take a database backup first. v1.1.0 can still run on a v11 database if you need to roll back. Apps that pass their own appAccountToken should use HiwiKInsightKit 0.3.0.
Full changelog: v1.1.0...v1.1.1
v1.1.0
Added
v_user_summary.is_pro: current membership fromis_proin the latestuser.snapshot, or an App Store purchase or trial start confirmed after it and not since expired, refunded or revoked. Unlikeis_paid, it includes members who bought before the SDK was integrated or restored a purchase. Theusersmetric gains apro=1filter, anis_procolumn andpro_usersin its summary; the dashboard shows a Pro badge and a "Pro only" filter, which replace the Paid badge and the "Paid only" filter (is_paidandpaid=1remain in the query API for purchase attribution). Adds database migration v10 (recreates the view, no data change).
Upgrade: replace the binary or image and restart; migration v10 only recreates the v_user_summary view (no data change). Apps should report is_pro ("true"/"false") in user.snapshot for the Pro badge to cover members who bought before the SDK.
Full changelog: v1.0.0...v1.1.0
HiwiKInsight 1.0.0
First open-source release of HiwiKInsight: self-hosted product analytics and App Store revenue for indie iOS apps, built to be queried by AI agents as well as people.
Try it
docker run --rm -p 8080:8080 ghcr.io/redhiwik/hiwikinsight:v1.0.0 demo -data /data -listen :8080Then open http://localhost:8080/dashboard/ and sign in with demo / demo. Or download an archive below (it contains hiwikinsight, insight and config.example.yaml), or install the CLI with go install github.com/RedHiwiK/HiwiKInsight/cmd/insight@v1.0.0.
Swift SDK: HiwiKInsightKit 0.2.0. Guides: Getting started, Deployment, AI integration.
What's included
- Single Go binary (
hiwikinsight) with embedded pure-Go SQLite (no cgo), subcommandsserve,demo,check-config,hash-passwordandversion. - One YAML configuration file with
${NAME}/${NAME:-default}environment expansion, strict validation, configurable reporting time zone, language (en/zh) and base currency. - Event ingestion (
POST /v1/events) for the HiwiKInsightKit Swift SDK (protocol schema 1): raw DEFLATE, limits, deduplication, clock correction, per-install daily cap, no IP addresses stored. - Derived tables for installs, daily activity and purchase attempts; analysis views
v_user_days,v_user_summary,v_sessions,v_screen_usage; raw event retention (retention_days). - "Truly new user" detection from the App Store original download date.
- Environment safety nets: production data from never-released builds and from development devices is reclassified as sandbox.
- App Store Server Notifications V2 (
POST /v1/appstore/notifications) with JWS verification, idempotent storage, base-currency conversion, transaction emails and purchase attribution throughappAccountToken. - App Store Connect sync: Summary Sales Reports (daily and monthly history), Analytics Reports (impressions, product page views, first-time downloads by source and country) and the released-build list.
- 15 built-in metrics with fixed definitions:
active_users,activity_days,retention,returning,module_usage,funnel,revenue,distribution,overview,sessions_daily,users,event_trend,errors,portfolio,store_funnel. - Read-only query API (
/v1/query/describe,meta,metric/{name},sql,user/{id}) with bearer tokens, a read-only SQLite connection and limits (single SELECT/WITH, 1000 rows, 10 s, 400-day range). describesemantic layer for AI assistants: conventions, tables, views, metrics, data volume, undocumented events and per-app event catalogs.insightCLI and a built-in MCP server (insight mcp) with the toolsdescribe,list_apps,metric,sqlanduser.- Claude Code skill
hiwikinsight-analytics. - Web dashboard with 13 pages (Portfolio, Overview, Engagement, Retention, Modules, Users, User detail, Acquisition, Revenue, Devices & Regions, Events, Errors, Settings), English and Chinese, light and dark mode, display currencies, bcrypt sign-in.
- Daily and weekly email reports with preview and resend endpoints.
- Alerts for failed purchases, payment errors, new and spiking errors, stale App Store Connect reports and silent apps, deduplicated per day.
- Demo mode with three sample apps and 90 days of generated data (
hiwikinsight demo,docker-compose.demo.yml,make demo). - Deployment assets: multi-arch container image on GHCR, Docker Compose with Caddy, systemd unit, nginx example, release archives for linux and darwin (amd64, arm64).
- Documentation in
docs/,AGENTS.mdfor AI coding agents, English and Chinese READMEs.