Class: ConvertSdk::SegmentsManager Private

Inherits:
Object
  • Object
show all
Defined in:
lib/convert_sdk/segments_manager.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Visitor segmentation — the REPORTING-data layer that attaches segment ids to a visitor's +StoreData+ in the JS SDK's wire shape (FR28–FR30). Ported from the JS SDK +packages/segments/src/segments-manager.ts+; the PHP reference is QUARANTINED here because it diverges on two wire keys.

== PHP-divergence #2 — the wire-key quarantine (FR30)

JS +SegmentsKeys+ (+segments-keys.ts:7-15+) emit camelCase: +visitorType+ / +customSegments+. PHP +SegmentsKeys.php:14-15+ emit snake_case: +visitor_type+ / +custom_segments+ — a real, disk-verified divergence. Segment data rides the tracking payload's +segments+ object (Epic 4 +ApiManager+ emits the visitor's stored +segments+ verbatim), so the wrong key would silently mis-filter every Ruby segment-report. Ruby follows JS: the seven report-segment keys, and +customSegments+ in particular, are the ONLY ones persisted, as camelCase STRINGS at rest in +StoreData+. The SegmentsManager never produces the PHP variants; Story 3.2's quarantine spec asserts their absence.

== The report-segment filter (#filter_report_segments, +data-manager.ts:1180-1199+)

Exactly seven keys are report-segments: +country+, +browser+, +devices+, +source+, +campaign+, +visitorType+, +customSegments+. #put_segments keeps ONLY these; every other key is silently DROPPED (JS routes them to a separate +properties+ bucket the segments layer ignores) — IGNORE, not reject. Ruby adds a +debug+ line naming the dropped keys (an observability addition; JS drops silently). A filter that leaves NOTHING is a no-op write (JS +if (reportSegments)+).

== Custom-segment evaluation REUSES the rule engine (#select_custom_segments)

+run_custom_segments+ does NOT introduce new rule logic. For each requested segment key it looks up the ConfigSegment entity (DataManager +segments+ reader), evaluates that segment's +rules+ against the supplied +segment_rule+ data via RuleManager#is_rule_matched (so NEED_MORE_DATA and every operator semantic come for FREE), and — on a match — appends the segment's id to the visitor's stored +customSegments+ list (deduped). A surfaced RuleError sentinel propagates out verbatim (mirrors JS +setCustomSegments+'s +Object.values(RuleError).includes(...)+ early-return).

== Persistence

All writes flow through the DataStoreManager atomic visitor-data merge (Story 2.1) into +StoreData["segments"]+. Stored data is string-keyed wire-world by design (so Epic 4's payload builder needs zero translation).

Constant Summary collapse

CUSTOM_SEGMENTS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

The +customSegments+ wire key — byte-identical to JS +SegmentsKeys.CUSTOM_SEGMENTS+ (+segments-keys.ts:14+). The visitor's matched custom-segment ids live under this key in +StoreData["segments"]+.

"customSegments"
SEGMENTS_KEYS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

The full report-segment key set — byte-identical to JS +SegmentsKeys+ (+segments-keys.ts:7-15+). The report-segment filter is restricted to exactly these seven; +visitorType+/+customSegments+ are the JS wire keys that diverge from PHP's snake_case variants (FR30). The SINGLE source of the allowed set.

%w[
  country browser devices source campaign visitorType customSegments
].freeze

Instance Method Summary collapse

Constructor Details

#initialize(data_manager:, data_store_manager:, account_resolver:, project_resolver:, rule_manager:, log_manager: nil) ⇒ SegmentsManager

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of SegmentsManager.

Parameters:

  • data_manager (DataManager) —

    the config reader surface (supplies the ConfigSegment entities by key and the account/project store-key halves).

  • data_store_manager (DataStoreManager) —

    the persistence port (atomic visitor-data merge into +StoreData["segments"]+).

  • account_resolver (#call) —

    resolves the account id (store-key half).

  • project_resolver (#call) —

    resolves the project id (store-key half).

  • rule_manager (RuleManager) —

    the Epic 2 rule walker reused for custom-segment evaluation (never re-implemented here).

  • log_manager (LogManager, nil) (defaults to: nil) —

    optional logger; debug on misses/drops, warn on already-present ids.



72
73
74
75
76
77
78
79
80
 
# File 'lib/convert_sdk/segments_manager.rb', line 72

def initialize(data_manager:, data_store_manager:, account_resolver:,
               project_resolver:, rule_manager:, log_manager: nil)
  @data_manager = data_manager
  @data_store_manager = data_store_manager
  @account_resolver = 
  @project_resolver = project_resolver
  @rule_manager = rule_manager
  @log_manager = log_manager
end

Instance Method Details

#put_segments(visitor_id, segments) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Set default report-segments for a visitor (JS +setDefaultSegments+ -> +putSegments+, +context.ts:434-436+ / +segments-manager.ts:78-85+).

The supplied segments are passed through #filter_report_segments (only the seven SEGMENTS_KEYS survive); a non-empty result is merged into the visitor's +StoreData["segments"]+ via the atomic store merge. An all-dropped input is a no-op (JS +if (reportSegments)+).

Parameters:

  • visitor_id (String)
  • segments (Hash) —

    the candidate report-segments (string-keyed wire shape).



93
94
95
96
97
98
99
 
# File 'lib/convert_sdk/segments_manager.rb', line 93

def put_segments(visitor_id, segments)
  report_segments = filter_report_segments(segments)
  return if report_segments.empty?

  merge_segments(visitor_id, report_segments)
  nil
end

#select_custom_segments(visitor_id, segment_keys, segment_rule = nil) ⇒ Hash, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Evaluate the named custom segments for a visitor and attach matching ids (JS +selectCustomSegments+ -> +setCustomSegments+, +segments-manager.ts:153-185+).

Each requested key is resolved to a ConfigSegment via the DataManager +segments+ reader; the segment's +rules+ are walked against +segment_rule+ by RuleManager#is_rule_matched. A surfaced RuleError sentinel propagates out verbatim (no attachment). Matching segment ids are appended to the visitor's stored +customSegments+ list (deduped); an unknown key is skipped with a debug log.

Parameters:

  • visitor_id (String)
  • segment_keys (Array<String>) —

    the segment keys to evaluate.

  • segment_rule (Hash, nil) (defaults to: nil) —

    the visitor data the segment rules match against; +nil+ attaches every resolved segment unconditionally (JS: +if (!segmentRule || segmentsMatched)+).

Returns:

  • (Hash, Sentinel, nil) —

    the updated segments hash, a propagated RuleError, or +nil+ when nothing matched.



118
119
120
121
 
# File 'lib/convert_sdk/segments_manager.rb', line 118

def select_custom_segments(visitor_id, segment_keys, segment_rule = nil)
  segments = lookup_segments(segment_keys)
  set_custom_segments(visitor_id, segments, segment_rule)
end