iris-analytics
Connect a product repository to Iris analytics using OAuth MCP; guide sign-up/sign-in, reuse or create a project, inspect code, plan and add events with Chinese labels, create funnels, verify ingestio
SKILL.mdskills/iris-analytics/SKILL.md
GitHubIris Analytics
Use Iris through the user's OAuth-authorized MCP connection. Never ask for, display, or store an Iris password, access token, refresh token, project secret, or personal MCP token.
Workflow
- Inspect the repository before proposing events.
- Run
node scripts/detect-project.mjs <repo>from this skill directory when available. - Use its
source_roots,deploy_roots, andentrypointsto identify maintainable source before reading generated output. - Identify framework, routes/pages, real account authentication state changes, forms, primary calls to action, success callbacks, and logout. A generic contest or application registration form is not account authentication by itself.
- Read only. Do not edit yet.
- Treat
recommended_domainas a candidate, not proof. Whendomain_conflictis true, inspect the listed evidence and verify the live production host from deployment/nginx configuration or the public page before any Iris project match/create/update. Nginxserver_nameand canonical production URLs outrank staleAppEnvvalues.
- Run
- Connect Iris.
- If Iris MCP tools are unavailable, tell the user to add
https://iris.teown.com/mcp; let the MCP client open OAuth. - If the browser opens login/registration, guide the user there. Do not automate credentials or verification codes unless the user explicitly provides the code for the active form.
- Request only the scopes needed for this task. Start with
analytics:read; addworkspace:write,report:export, oranalytics:raw-exportonly when needed. - Non-interactive
codex execvalidation needs an approvable local policy:approval=neverrejects MCP tool calls. Prefer interactive approval; use--approve-for-meonly after the user-approved prompt is constrained to exact targets and writes. This does not bypass OAuth scopes or project roles.
- If Iris MCP tools are unavailable, tell the user to add
- Reuse before creating.
- Call
list_projectsand match the production project by a verified normalized domain or Mini Program AppID, then by exact name. Do not use a stale source-code environment mapping as the sole domain authority when deployment evidence conflicts. - If one unambiguous production project matches, reuse it. If none match, propose
create_project. If multiple match, ask the user to choose. - For ingestion verification, separately match the exact name
<production project name> · 接入测试and its non-production domain. Reuse that project across runs; create it only with the user's approved writes. Never send synthetic verification events to the production project by default. - Read
references/test-isolation.mdbefore creating or reusing a verification project.
- Call
- Produce the complete plan before writes.
- Event names: lowercase English
snake_case. - Every business event has a concise Simplified Chinese label and description.
- Include trigger, exact code location, safe properties, identity timing, and funnel membership.
- Set
identity.modetoanonymousorauthenticated; do not infer account identity from a generic registration form. - Set
verification.strategytoreusable_test_projectwith its deterministic test project name and domain. - Use 2–8 steps per funnel; prefer observable business outcomes over clicks.
- Run
node scripts/validate-event-plan.mjs <plan.json>when a JSON plan is produced.
- Event names: lowercase English
- Ask once for confirmation covering both repository edits and Iris configuration writes.
- Apply idempotently.
- Call
get_sdk_setupfor both the reusable test project and the production project. Test/development deployments use the test App ID; production configuration uses the production App ID. - Follow the stack-specific reference. Never edit minified or hashed bundles, or a detected
deploy_root, directly; edit maintainable source and use the repository's build process. - Preserve existing analytics and project conventions.
- Do not add duplicate SDK initialization or duplicate event calls on rerun.
- For
identity.mode=authenticated, callidentify(stableAccountId)immediately after authentication succeeds and before the first authenticated success event. Callreset()on logout before another person can use the same client state. - For
identity.mode=anonymous, do not add fake identity calls merely to satisfy static checks. - Do not use email, phone, OpenID, UnionID, or another direct personal identifier as the analytics identity. Prefer an internal opaque account ID.
- Upsert dictionary entries with a new UUID
request_idfor each intended write. Before writing a funnel, calllist_funnels: reuse an exact match, update one exact-name mismatch withupdate_funnel, and create only when no exact-name funnel exists. If multiple exact-name funnels exist, stop and ask which one to keep. Reuse the same UUID only when retrying that exact write. - If an existing Iris project's stored domain/AppID is stale and the live target is verified, use
update_projectwith only thedomainfield plusproject_idand a new UUID. Never change project type, App ID, secret, ownership, or membership as part of domain reconciliation. - For
upsert_event_dictionary, map the plan'seventtoitem.event_type. Property definitions useproperty_key,label,value_type,is_required, anddescription; map plan typesenum → string,boolean → bool, andcount → number.
- Call
- Verify.
- Run project tests/build.
- Run
node scripts/verify-integration.mjs <repo> <plan.json>for static integration checks. - Exercise the real UI flow against the reusable test project's App ID when the environment permits.
- Query
get_eventsandget_funnelon the test project after ingestion. Code presence or HTTP 200 alone is not ingestion proof. - Verify the production configuration statically and wait for a natural production event unless the user explicitly authorizes a synthetic production event.
- State clearly when real interaction or ingestion is still unverified.
- Export only on request.
- Use
start_report_exportthen pollget_export_jobfor PPTX. - Use
start_data_exportonly after explaining that it exports redacted event rows and requires Owner/Admin. - Download links expire after 24 hours; do not commit or repost them.
- Use
Privacy hard stops
Never track password or verification-code fields, cookies, authorization headers, access/refresh tokens, full query strings, raw form text, email, phone, bank-card or government-ID values. Do not add tracking that reads input values. Prefer enum/boolean/count properties with an explicit allowlist.
Supported automation
- Vanilla JS/TS: read
references/web-instrumentation.md. - React + Vite: read
references/web-instrumentation.md. - Vue + Vite: read
references/web-instrumentation.md. - Legacy multi-root Web projects with maintainable
dev/or similar source and generatedprd/output: readreferences/legacy-web-instrumentation.md. - Native WeChat Mini Program: read
references/wechat-miniprogram.md. - Next.js, Nuxt, Taro, uni-app, or unknown stacks: produce a manual plan and stop before edits unless the user supplies project-specific integration guidance.
Read references/event-design.md for event planning, references/funnels.md for funnel rules, references/exports.md for exports, and references/security.md for permission/privacy details as needed.