adsparkle_flutter 0.1.9

Flutter client SDK for the AdSparkle affiliate attribution tracking platform. Deterministic Android install attribution via the Play Install Referrer; pure Dart on every other platform.

Changelog

0.1.9

• The iOS /match debug message now includes the reason when no click is matched: Eslestirme sonucu yok (<reason>), where the reason is no_match, ambiguous, ambiguous_device_profile, network_error, invalid_response or http_<code>. Previously every outcome was shown as no_match, which hid the difference between "no matching click", "several possible clicks" and "server unreachable".
• MatchClient.resolveMatch now returns a MatchOutcome (click id and reason) instead of a nullable click id.
• README: baseUrl should be the domain your tracking links are served from. On iOS, deferred attribution can fail when links and SDK requests use different hosts.

0.1.8

• On-screen debug diagnostics. With configure(debug: true) the SDK now emits 13 short diagnostic messages for every critical step (ready, link received, click_id from link, link not recognised, registering click, click_id received, register-click rejected/retrying, /match resolved/no result, event deferred/sent/rejected) so an integrator can see where the chain breaks on a real device without attaching to flutter run / Xcode / logcat.
• New AdSparkleDebugOverlay widget: wrap your app (typically in MaterialApp.builder) to render the messages at the bottom of the screen — tap to expand/collapse, long-press to copy the whole buffer to the clipboard, and buttons to clear or dismiss. The message list is IgnorePointer, so it never blocks the UI underneath.
• New setDebugHandler((message) { ... }) for apps that prefer their own toast/snackbar, plus low-level subscribeDebug(...) and the SDK_VERSION constant. A handler takes priority over the overlay — a message is shown exactly once, never twice.
• Message texts are byte-identical to the iOS, Android and React Native SDKs.
• Zero production impact: with debug: false (the default) no diagnostic string is ever built, no listener is called and the overlay renders only its child. Secrets are never shown — click_id is truncated to its first 8 characters, URLs/keys to 60; companyKey and device_id never appear.

0.1.7

• New attribution callback: AdSparkle.instance.onClickId = (clickId) { ... } fires the moment a click_id becomes active, from any source (deep-link ?click_id, register-click, Play Install Referrer, iOS /match) — no polling needed. If a click_id already exists when the handler is set, it is invoked immediately (once, asynchronously) with the current value. The same value never fires twice in a row; a different new value fires again. Delivery is async (microtask) and never runs inside SDK state updates. Optional and backwards compatible — reading clickId still works.

0.1.6

• Deep-link unique_key is now the last non-empty path segment, matching the backend /:appSlug?/:uniqueKey route (multi-app /slug/key links; single-segment links are unchanged).
• Link-host acceptance now also matches the configured baseUrl host, plus an optional configure(extraLinkHosts: [...]) list (equal or .suffix match, trimmed and lowercased). Existing configure calls are unchanged.
• Sticky click_id fix: an existing click_id no longer blocks register-click for a new link tap — the new id unconditionally becomes active and joins the chain. An expired (7-day TTL) chain now also clears the persisted scalar click_id.
• register-click failures are classified: 4xx (except 408/429) is permanent — the pending request is cleared (unblocking the Android Install Referrer fallback); 5xx/408/429/network errors keep it for retry. Pending is cleared with compare-and-clear so an in-flight response never wipes a newer tap, and an in-flight guard prevents duplicate register-click POSTs.
• track() retries a pending register-click even when a click_id already exists.
• Postbacks now treat HTTP 408/429 as retryable (queued) instead of permanent.

0.1.5

• configure() now accepts an optional linkDomainSuffix (default .go.adsparkle.co) so test/prod deployments can use different link domains, mirroring the backend LINK_DOMAIN_SUFFIX env. Existing calls are unchanged.
• Deferred attribution: Play Install Referrer capture, probabilistic /match, and register-click for app-installed universal-link opens.

0.1.4

• Rebrand: package description, docs and license now reference AdSparkle (formerly "Viralif / AdBird"). No code changes.

0.1.3

• Accept company custom-event shortIds (e.g. YE2YFSQ) as eventType — the fixed 7-event allowlist was relaxed to the backend format ^[A-Za-z0-9_]{1,64}$. Built-in typed helpers are unchanged.
• AdSparkleEvent.eventType is now the raw wire string, so queued custom events survive persistence and offline replay.
• Documented productIds / customParams support (product-scoped campaigns).

0.1.2

• Default API base URL is now https://api.adsparkle.co (was api.viralif.co).
• Aligned with the Web/RN/Android/iOS SDK family.

0.1.0

Initial release.

• Singleton AdSparkle.instance public API.
• configure(), setUserId(), setClickId(), handleDeepLink().
• track() plus typed helpers: trackInstall, trackSignUp, trackLogin, trackDownload, trackPurchase, trackSubscription, trackRefund.
• Deep link click_id extraction from URI query parameters.
• Click chain persistence (de-duplicated, max 10 entries).
• Postback delivery to POST {baseUrl}/api/tracking/postback with X-Company-Key auth (publishable co_ key; no secret/HMAC).
• Exponential backoff retry (3 attempts) on 5xx / network errors.
• Persisted pending queue (shared_preferences) flushed on the next configure() / track().