intercept
A transport that runs transform on every event before handing it to this one: to redact a property, add one, or drop the event (return null) for sampling (#302).
val tracker = Autograph {
transport(SegmentTransport(analytics).intercept { event -> event.withProperties(event.properties - "email") })
}Prefer this to a hand-written Transport wrapper. The returned transport forwards every member — Transport.stampsInPipeline, Transport.connect, Transport.flush, Transport.reset — and routes both of an event's overloads through transform exactly once, so an event that carries EventMetadata is transformed like any other and keeps its metadata. It implements MetadataAwareTransport exactly when this transport does (looking through DebugTransport and other intercept layers), so the tracker warns about a lost capability once and names the transport that loses it, as it does for this transport unwrapped. A wrapper your app wrote is not looked through: over one that does not implement MetadataAwareTransport, events lose their metadata as they did before. A delegate written in Swift receives nested values as their JSON text, as it does from the tracker itself (#299).
Reach for the tracker's own hooks first: a key every event needs belongs in DefaultProperties, and a rule about which events are allowed belongs in AutographConfig.validator. Both run before this, for track and screen (the tracker applies neither to identify).
What transform sees and may change. Each track, screen and identify call the tracker hands to this transport becomes one TransportEvent; an event the validator rejected, or one sent after the tracker closed, never reaches it. Only the properties of the event transform returns are read: the type and name (the user id, for identify) cannot change, and the Envelope and EventMetadata travel past transform untouched. transform runs after AutographConfig.validator, so what it returns is not validated again. A track event's properties already hold the reserved target key the tracker adds for an element, so a transform that keeps only known keys has to keep target too. A RESERVED_METADATA_KEY the transform adds to a track or screen event is removed, because the tracker promises a transport those properties without it (MetadataAwareTransport); identify traits are handed on as returned, as the tracker hands them on unwrapped. Through the tracker, an identity transform (intercept { it }) changes nothing a transport receives.
Dropping an event. On a transport the core stamps for (stampsInPipeline == false, such as SegmentTransport on iOS) the envelope was stamped before transform runs, so a dropped event leaves a gap in seq. On a pipeline transport (SegmentTransport on Android) nothing is stamped for it, so it leaves none. A warehouse that reads seq gaps as loss counts sampled events as lost on the first kind only.
Logging. DebugTransport logs what reaches it. To log what this transport sends, put it inside: DebugTransport(delegate).intercept(redact) logs the properties after transform; DebugTransport(delegate.intercept(redact)) logs them before, unredacted. The event name, the user id and the metadata are outside transform's reach either way.
Threading and lifetime. transform runs on the caller's thread for a pipeline transport and on the tracker's serial dispatcher otherwise, so it must be thread-safe and fast. The returned transport holds transform, and everything it captures, for as long as the transport itself is held, which is usually the life of the process: do not capture an Activity or a view. If transform throws, the event is not delivered, and the tracker reports the failure through AutographConfig.logger and counts it in CloseResult.failedHandOffs, as it does for a transport that throws. A null return is a deliberate drop and is not counted.
Kotlin only: hidden from Swift and Objective-C. A Swift closure would receive TransportEvent.properties as a [String: JsonElement] dictionary and trap on a nested value (#299).