liquid_segment

Segment destination for liquid_analytics — Segment as one sink among many, not as liquid's hub.

liquid already owns multi-provider fan-out and consent. This package only forwards the normalized envelope to Segment Cloud so you can still use Segment destinations when you want them, without routing every other provider through Segment.

Install

dependencies:
  liquid_analytics: ^0.2.0
  liquid_segment: ^0.2.0

Use

final liquid = Liquid(
  sinks: [
    SegmentSink(writeKey: 'YOUR_WRITE_KEY'),
    // Plus any other liquid adapters — they are peers, not Segment plugins.
    // FirebaseSink(), PostHogSink(...), ...
  ],
  consent: ConsentPolicy(
    requireOptIn: true,
    map: {ConsentCategory.analytics: ['segment']},
  ),
);
await liquid.init();

liquid.track('checkout_started', {
  'cart_value': 42.0,
  'is_gift': true,
});
liquid.consent.grant(ConsentCategory.analytics);

If Segment is already initialized, inject the client:

final analytics = createClient(Configuration('YOUR_WRITE_KEY'));
final liquid = Liquid(sinks: [SegmentSink(analytics: analytics)]);

Typed events (recommended)

The string API above is the quick path. A typed event keeps the name and property keys in one place — and because Segment is a peer sink rather than the hub, one definition fans out to Segment and every other adapter at once, with no per-destination call sites:

class CheckoutStarted extends LiquidEvent {
  const CheckoutStarted({required this.cartValue, this.isGift = false});
  final double cartValue;
  final bool isGift;

  @override
  String get name => 'checkout_started';

  @override
  Map<String, Object?> get properties => {
        'cart_value': cartValue,
        'is_gift': isGift,
      };
}

// Reaches Segment, and any peer sinks, from this single call.
liquid.log(const CheckoutStarted(cartValue: 42, isGift: true));

Override category to route an event to a different consent bucket (e.g. ConsentCategory.marketing). No build step is involved — these are plain classes. To generate them from a YAML schema instead, see liquid_codegen.

Message mapping

Segment's Spec matches liquid 1:1:

liquid message	Segment call
track	track
screen	screen
identify	identify
group	group
alias	alias
reset	reset

Trait handling

SegmentPropertyMapper converts liquid's free-form trait maps into Segment's typed UserTraits / GroupTraits:

• reserved Spec keys (email, name, plan, …) land on typed fields
• everything else goes under custom
• null values are dropped; DateTime / Enum are normalized

Positioning vs using Segment alone

	Segment SDK alone	liquid + liquid_segment
Multi-provider fan-out	Destination plugins only	Any LiquidSink peer
Consent gate	Your code	Built into liquid
Typed events	Your code	liquid sealed-class API
Segment Cloud	Yes	Yes (this package)

Use this adapter when Segment is one of your destinations. Do not add Segment destination plugins for providers that liquid already covers — that would double-send.

Testing

SegmentPropertyMapper is a pure transform and is unit-tested without a live workspace. For end-to-end checks, use a Segment source write key and inspect the Debugger.