snowplow / snowplow/documentation
[AISP-1030] Document beforeTrack plugin callback in mobile tracker docs
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 8
- Forks
- 9
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 18
Description
Implementation task — AISP-1030
What
Add a new "Intercepting events before they are tracked" section to the mobile tracker plugin documentation, covering the beforeTrack callback now available in both the iOS and Android trackers.
Why
beforeTrack is a new plugin callback that lets host apps overwrite or add event payload fields before events are sent to the collector — for example, stripping sensitive fields when a user has only partially consented. Without documentation the feature is not discoverable, and three non-obvious constraints (thread-safety, overwrite/add-only semantics, raw key names) need to be surfaced prominently to prevent misuse.
Approach
Insert a new subsection immediately before the existing "Inspecting events after they are tracked" (afterTrack) section in the mobile plugin docs, mirroring its tab-based code-example structure (iOS Swift / Android Kotlin / Android Java). The primary code example should illustrate consent-based field stripping. Three constraints must be called out explicitly as noted in Changes below.
Depends on
- Both the
snowplow-ios-trackerandsnowplow-android-trackerbeforeTrackPRs must be merged and released before this PR is merged, so that code examples reference the released API rather than unreleased snapshots.
Changes
docs/sources/mobile-trackers/plugins/index.md— MODIFY — Add a new### Intercepting events before they are trackedsection immediately before the existing### Inspecting events after they are trackedsection (currently around line 162). The section must include:- A consent-based field-stripping code example in iOS (Swift) and Android (Kotlin + Java) tabs, using the same tab structure as the
afterTracksection. - An explicit callout that on iOS the closure runs on the tracker's
InternalQueue: a blocking call inside the closure (e.g. synchronous I/O or a lock wait) will stall event tracking. - A callout that v1 supports overwrite and add only — returning a key with a new value overwrites it in the payload; key removal is not supported in this release.
- A note that the payload is keyed by raw tracker field names (e.g.
url,se_ca) rather than the final collector field names.
- A consent-based field-stripping code example in iOS (Swift) and Android (Kotlin + Java) tabs, using the same tab structure as the
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open docs/sources/mobile-trackers/plugins/index.md and read the existing “Inspecting events after they are tracked” section for its tab structure. Add the preceding beforeTrack section with Swift, Kotlin, and Java consent-based examples, then verify it documents the iOS InternalQueue constraint, overwrite/add-only behavior, and raw tracker field names.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, ios, java, kotlin, swift
- Domain
- documentation, mobile
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100