snowplow / snowplow/documentation

[AISP-1030] Document beforeTrack plugin callback in mobile tracker docs

Open Beginner friendly
#1,802 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

implement
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-tracker and snowplow-android-tracker beforeTrack PRs 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.mdMODIFY — Add a new ### Intercepting events before they are tracked section immediately before the existing ### Inspecting events after they are tracked section (currently around line 162). The section must include:
    1. A consent-based field-stripping code example in iOS (Swift) and Android (Kotlin + Java) tabs, using the same tab structure as the afterTrack section.
    2. 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.
    3. 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.
    4. A note that the payload is keyed by raw tracker field names (e.g. url, se_ca) rather than the final collector field names.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.