# Assistant setup 2026-10-14.1

Open the owned project's Setup page to get its scoped context and public SDK key. Connect to https://extension.report/mcp; request setup:write and grant exactly one owned project. Existing read grants never imply configuration permission.

Tools: get_setup_plan, configure_sdk, discover_store_sources, configure_store, verify_setup. Supported automatic store bindings: Firefox public, Edge public, existing Chrome OAuth, existing GA4 OAuth. Direct Safari and Apple customer connectors remain guided/manual or unavailable. Never publish, rotate keys, change billing or delete data. Secrets stay in secure owner screens and local secret managers.

Use the published SDK 0.6.4. Install @extension-report/js@0.6.4 with the repository's existing package manager; keep exact versions and the lockfile.

Inspect the existing repository before changing it: framework, MV2/MV3 background, package manager, manifests, supported browsers, singleton telemetry wrapper, runtime messaging, auth, license/trial state, purchase confirmation and consent setting. Do not replace an existing SDK instance or duplicate listeners.

Determine whether this is WXT, Plasmo, a plain WebExtension or a native Safari container. Do not choose a framework from the project name. Save the detected profile before implementation.

Initialize a single background/service-worker instance with projectPublicKey="pk_er_YOUR_PROJECT_PUBLIC_KEY" and instrumentation adoption:true, engagement:true, reliability:"errors". Preserve existing ceilings/settings when integrating an already-instrumented extension. No owner secret belongs in a browser package.

Merge storage, alarms and the exact Extension Report API origin into the built manifest. Preserve other permissions and CSP. Add optional feature permissions only when the extension actually uses those APIs. For Firefox, inspect required/optional data_collection_permissions and honor the technical-data grant on supported versions; do not bypass or silently reset it. For WXT, use its module or manual background integration consistently; never enable both autoBackground and a duplicate manual SDK.

Connect actual popup/options/side-panel sessions with connectExtensionReportUiSession({surface}); content scripts send narrowly validated messages to the background. Validate message type, payload and sender. Never initialize a second SDK in each UI or content script.

Selected surfaces: inspect existing surfaces. Detect absent surfaces; do not create product UI merely for telemetry.

Keep anonymous installations anonymous. If trials exist without accounts, call sdk.identify(null, safeEntitlementTraits); do not generate a fake user or use installation ID as an account identity.

Reuse existing custom event names for equivalent transitions; the trial/subscription/purchase names above are examples when no equivalent event exists. Inspect the event catalog and preserve continuity. Product-specific signals use sdk.trackCustomEvent(name, safeAttributes). The SDK has no trackPurchase or trackTrial method. TrackOptions supports flush only; implement transition/transaction deduplication in the application's existing persisted state, not a made-up SDK dedupe option. Keep backend revenue separate from client-observed checkout and entitlement events.

Identify the product's existing meaningful-value event with the owner; do not equate activation with installation or opening the popup.

Keep a visible tracking preference and honor existing opt-out/consent. sdk.setTrackingEnabled(false) must stop collection; restoring consent must not backfill suppressed actions. Never collect emails, payment tokens, receipt bodies, document text, full visited URLs or browsing history.

Validate with @extension-report/doctor@0.6.4 against each generated store manifest. Test clean install versus update, service-worker restart, popup/options sessions, offline replay, opt-out, logout/account switch, anonymous trial start/expiry/conversion, canceled subscriptions and duplicate purchase callbacks where applicable. First run against a local/test project or debug.dryRun; do not fabricate financial events in the owner's live project.

Report source edits, built artifact, installed extension and server-observed events as separate verification steps. Existing events are a baseline, not proof that the new build works. Do not commit, publish, deploy or upload a store package without authorization for that action.

## Free trials
Read authoritative entitlement state on startup and on changes. Support anonymous trials without inventing an account. Identify with entitlement_type, entitlement_status, plan_code and trial_expires_at. Emit trial_started, trial_expired and trial_converted only on verified transitions; persist transition deduplication in existing local storage. Never emit on every poll or backfill old starts on an upgrade.

## Subscriptions
Use server-verified plan and subscription state. Distinguish checkout_opened from subscription_activated, canceled, renewed and expired. Cancellation scheduled for period end is not loss of access now. Identify the entitlement snapshot on changes. Payment webhooks are the authority; client observations are not audited revenue.

## One-time purchases
Track purchase_confirmed only after backend or store receipt validation. Use the existing transaction identity for persistent deduplication; do not send receipts, license keys or payment identifiers. Treat refunds separately. If you send amounts, use integer minor units and an explicit ISO currency; do not sum currencies or promise revenue reports unsupported by Extension Report.

## Credits and usage billing
Track verified credit/entitlement changes separately from product usage. Use sdk.count for frequent feature actions; counters are not billable usage or an accounting ledger. Avoid raw prompts, documents, browsing history or customer content. Charging remains in the existing backend.

## Chrome Web Store
OAuth read connection
Fields: Chrome extension ID, Publisher ID, Google connection, GA4 source
1. Save the existing Chrome extension ID; verify that its public listing is the intended product.
2. Use Settings → Connect Chrome Web Store, complete Google consent in the secure browser, then select the existing connection and Publisher ID. Do not create a Google Cloud project for each customer.
3. Use Acquisition → Connect Google Analytics. Select the Google account that can access the Chrome listing's GA4 source. Additional metrics must be enabled in the Chrome Web Store dashboard.
4. Discover available sources, select the exact matching listing, and verify the binding before synchronization. A successful connection does not guarantee data; thresholded and missing counts stay unknown.
5. Check Releases for published/submitted versions and Acquisition for the last successful sync, source timezone and reporting coverage.
References: https://developer.chrome.com/docs/webstore/metrics https://developer.chrome.com/docs/webstore/api/reference/rest/v2/publishers.items/fetchStatus

## Firefox Add-ons
Public listing · no API key
Fields: AMO listing URL, slug or add-on ID
1. Find the public AMO listing for the exact extension. Do not infer identity from its name alone.
2. Save its URL or add-on ID. No publishing key is required for public version, average daily users, weekly downloads or ratings.
3. Verify the returned add-on identity, public version and successful check time. Public counters are observations, not reconstructed daily private statistics.
4. Keep Mozilla publishing credentials in the user's own release environment. Private developer statistics require a separate supported source; they are not unlocked by this public connector.
References: https://mozilla.github.io/addons-server/topics/api/addons.html

## Microsoft Edge Add-ons
Public listing + private CSV reports
Fields: Edge listing URL or CRX ID, Partner Center Product ID, Submission reporting token
1. Save the public Edge CRX ID; it differs from the Partner Center Product ID and the Chrome extension ID.
2. Verify the public version, users and check time. This public listing does not expose certification status.
3. For release-command tracking, copy the Partner Center Product ID and configure a random project-scoped reporting token using Settings and the user's secret manager. Extension Report stores its hash, never Microsoft publication credentials.
4. Keep Edge publishing keys in the local release environment. Point the publication command to the displayed project endpoint. Verify a real command receipt when a future authorized submission occurs; do not publish a package just to test configuration.
5. For private analytics, export Weekly users, Installs and Impressions from Partner Center. Allow that site's downloads if Chrome blocks them. Import each with the matching measure. Standard item exports include applicationId; distribution exports with dynamic columns must be normalized with their known listing, measure and dimension before import.
6. Verify period, enabled state, country, language and OS. Weekly populations cannot be added across weeks; missing report days are not zero. Analytics are CSV imports, not an undocumented publishing-API feature.
References: https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/extensions-analytics https://learn.microsoft.com/en-us/microsoft-edge/extensions/update/api/addons-api-reference

## Safari · direct distribution
SDK + updater feed · guide only
Fields: Signed updater feed URL, Containing app and extension identity
1. Inspect the containing macOS application and Safari extension separately. Installation, app launch and actual extension use are distinct events.
2. Identify the existing signed updater feed and release process. Never replace signing identities or notarization credentials during telemetry setup.
3. Integrate the JS SDK only where the existing Safari Web Extension architecture supports it. Route native app events through an existing validated bridge; do not invent a native SDK.
4. Verify extension enablement, a real extension UI session and update checks with the installed app. Direct distribution has no App Store analytics source.
5. Automatic feed configuration is not implemented in Extension Report yet; keep the manual guide explicit.
References: https://developer.apple.com/documentation/safariservices/safari-web-extensions https://sparkle-project.org/documentation/

## Safari · App Store
Internal pilot · customer connector pending
Fields: App Store app ID, Bundle ID, Issuer ID and reader key in secure storage
1. Identify the containing Mac App Store app and its Safari extension. Confirm the current public storefront version; READY_FOR_SALE history alone is not proof of the latest live version.
2. Review the Apple API agreement applicable to the customer's team. Our internal AMOREM pilot does not authorize a commercial third-party key connector.
3. For authorized internal use, the team owner enables App Store Connect API access and stores a Sales and Reports key securely. Never paste a .p8 key into an assistant prompt. Publication credentials remain separate.
4. An authorized administrator initializes an ONGOING Analytics report request for the exact app. Reader access alone cannot perform this initialization.
5. Wait for generated instances. A catalog definition or successful request is not a downloadable report. Preserve report/instance/segment identity, processing dates, corrections and privacy thresholds.
6. Treat Safari Extensions Usage/Enablement separately from containing-app downloads/sessions. This customer connector is not currently available in Extension Report; the assistant must report that boundary rather than claim it connected.
References: https://developer.apple.com/documentation/appstoreconnectapi/analytics https://developer.apple.com/documentation/analytics-reports/safari-extensions-usage https://developer.apple.com/documentation/analytics-reports/safari-extensions-enablement