oursprivacy-ingest 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ed1b63854906efe0f462b08eaf8cb9de0ff4a4586e13ce25159e54371939947
-  data.tar.gz: 0531b08a511ed70b76b42a47d2541dfdf11fc388cce6b0a03f53f8f8017d3cde
+  metadata.gz: d23eb81e41813ee04947b2d1a04f410bf7b8198b2d958ae79042ca379162e62c
+  data.tar.gz: e8a0964d9d45ad11a6a2cc5dd44be08af26382036c5c95e6d6790aacd75f4817
 SHA512:
-  metadata.gz: e629ea80c262196d7cf71ccf58a9ed7dcbc6ea633e7c89863a344dbc8dd24c48dcd58ce18881842989aa85986c62b3c8ff1d393b88eaec7a43444b4dc0dce7aa
-  data.tar.gz: fca70c8d6c4c831dd2a624d409e244ebabe7ed4865de14b55aad2c5b9e4f3152d7c7ed5dde54e0f7507fa6a1a73fb97e96dbe9ffa677940eb3b65c3e9719bafe
+  metadata.gz: 2e933d84b08922ee6f9885e9fadb991b4d237a97ed77be3b2672d1e6e59564b1f15e5f9a761cb572fddb1af0c4ccc393137f9b51eccfe371dc1fe6b0661ab75c
+  data.tar.gz: c9575d16b3128719b6aac612889144486685e7894835970a813ccd2258090668507e5e8e50d48dcdfb6bd648d421d6d1b8e2da4bcbeb856bcb9a470bc356f482

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.6.0 (2026-05-07)
+
+Full Changelog: [v1.5.0...v1.6.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.5.0...v1.6.0)
+
+### Features
+
+* **api:** api update ([c54431d](https://github.com/with-ours/ingest-sdk-ruby/commit/c54431d5d205b735a570afa625a3b8e4bdd8c67d))
+
 ## 1.5.0 (2026-05-06)
 
 Full Changelog: [v1.4.0...v1.5.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.4.0...v1.5.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "oursprivacy-ingest", "~> 1.5.0"
+gem "oursprivacy-ingest", "~> 1.6.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/oursprivacy_ingest/models/batch_create_params.rb

@@ -29,7 +29,10 @@ module OursprivacyIngest
 
       class Event < OursprivacyIngest::Internal::Type::BaseModel
         # @!attribute distinct_id
-        #   A unique identifier for the event. This helps prevent duplicate events.
+        #   A unique identifier for this event used for deduplication. Highly recommended —
+        #   if omitted, Ours will generate one for you, but supplying your own gives you
+        #   stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+        #   internal order ID).
         #
         #   @return [String]
         required :distinct_id, String, api_name: :distinctId
@@ -52,9 +55,9 @@ module OursprivacyIngest
                  nil?: true
 
         # @!attribute email
-        #   The email address of a user. We will associate this event with the user or
-        #   create a user. Used for lookup if externalId and userId are not included in the
-        #   request.
+        #   The email address of a user. Used as a fallback lookup when neither userId nor
+        #   externalId is provided. We search your account for a visitor with this email and
+        #   attach the event to them. If no match is found, a new visitor is created.
         #
         #   @return [String, nil]
         optional :email, String, nil?: true
@@ -69,9 +72,11 @@ module OursprivacyIngest
                  nil?: true
 
         # @!attribute external_id
-        #   The externalId (the ID in your system) of a user. We will associate this event
-        #   with the user or create a user. If included in the request, email lookup is
-        #   ignored.
+        #   Your system's unique identifier for this user. We search your account for an
+        #   existing visitor with this externalId and attach the event to them (resolving to
+        #   their Ours Visitor ID). If no match is found, a new visitor is created. When
+        #   present, email lookup is skipped. If you also have the userId from cookies or
+        #   local storage, send both — it removes the lookup round-trip.
         #
         #   @return [String, nil]
         optional :external_id, String, api_name: :externalId, nil?: true
@@ -95,9 +100,10 @@ module OursprivacyIngest
         optional :time, Float, nil?: true
 
         # @!attribute user_id
-        #   The Ours user id stored in local storage and cookies on your web properties. If
-        #   userId is included in the request, we do not lookup the user by email or
-        #   externalId.
+        #   The Ours Visitor ID stored in local storage and cookies on your web properties.
+        #   When present, this is used directly — no lookup by externalId or email is
+        #   performed. If you have both a userId and an externalId, send both so the event
+        #   is attached to the right visitor without any lookup overhead.
         #
         #   @return [String, nil]
         optional :user_id, String, api_name: :userId, nil?: true
@@ -116,23 +122,23 @@ module OursprivacyIngest
         #   Some parameter documentations has been truncated, see
         #   {OursprivacyIngest::Models::BatchCreateParams::Event} for more details.
         #
-        #   @param distinct_id [String] A unique identifier for the event. This helps prevent duplicate events.
+        #   @param distinct_id [String] A unique identifier for this event used for deduplication. Highly recommended —
         #
         #   @param event [String] The name of the event you're tracking. This must be whitelisted in the Ours dash
         #
         #   @param default_properties [OursprivacyIngest::Models::BatchCreateParams::Event::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
         #
-        #   @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+        #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
         #
         #   @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
         #
-        #   @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+        #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
         #
         #   @param identity_context [OursprivacyIngest::Models::BatchCreateParams::Event::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
         #
         #   @param time [Float, nil] The time at which the event occurred in milliseconds since UTC epoch. The time m
         #
-        #   @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+        #   @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
         #
         #   @param user_properties [OursprivacyIngest::Models::BatchCreateParams::Event::UserProperties, nil] Properties to set on the visitor. (optional) You can also update these propertie
 

data/lib/oursprivacy_ingest/models/track_event_params.rb

@@ -31,15 +31,18 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute distinct_id
-      #   A unique identifier for the event. This helps prevent duplicate events.
+      #   A unique identifier for this event used for deduplication. Highly recommended —
+      #   if omitted, Ours will generate one for you, but supplying your own gives you
+      #   stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+      #   internal order ID).
       #
       #   @return [String, nil]
       optional :distinct_id, String, api_name: :distinctId, nil?: true
 
       # @!attribute email
-      #   The email address of a user. We will associate this event with the user or
-      #   create a user. Used for lookup if externalId and userId are not included in the
-      #   request.
+      #   The email address of a user. Used as a fallback lookup when neither userId nor
+      #   externalId is provided. We search your account for a visitor with this email and
+      #   attach the event to them. If no match is found, a new visitor is created.
       #
       #   @return [String, nil]
       optional :email, String, nil?: true
@@ -54,9 +57,11 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute external_id
-      #   The externalId (the ID in your system) of a user. We will associate this event
-      #   with the user or create a user. If included in the request, email lookup is
-      #   ignored.
+      #   Your system's unique identifier for this user. We search your account for an
+      #   existing visitor with this externalId and attach the event to them (resolving to
+      #   their Ours Visitor ID). If no match is found, a new visitor is created. When
+      #   present, email lookup is skipped. If you also have the userId from cookies or
+      #   local storage, send both — it removes the lookup round-trip.
       #
       #   @return [String, nil]
       optional :external_id, String, api_name: :externalId, nil?: true
@@ -80,9 +85,10 @@ module OursprivacyIngest
       optional :time, Float, nil?: true
 
       # @!attribute user_id
-      #   The Ours user id stored in local storage and cookies on your web properties. If
-      #   userId is included in the request, we do not lookup the user by email or
-      #   externalId.
+      #   The Ours Visitor ID stored in local storage and cookies on your web properties.
+      #   When present, this is used directly — no lookup by externalId or email is
+      #   performed. If you have both a userId and an externalId, send both so the event
+      #   is attached to the right visitor without any lookup overhead.
       #
       #   @return [String, nil]
       optional :user_id, String, api_name: :userId, nil?: true
@@ -107,19 +113,19 @@ module OursprivacyIngest
       #
       #   @param default_properties [OursprivacyIngest::Models::TrackEventParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      #   @param distinct_id [String, nil] A unique identifier for the event. This helps prevent duplicate events.
+      #   @param distinct_id [String, nil] A unique identifier for this event used for deduplication. Highly recommended —
       #
-      #   @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
       #   @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
       #
-      #   @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       #   @param identity_context [OursprivacyIngest::Models::TrackEventParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
       #   @param time [Float, nil] The time at which the event occurred in milliseconds since UTC epoch. The time m
       #
-      #   @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      #   @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       #   @param user_properties [OursprivacyIngest::Models::TrackEventParams::UserProperties, nil] Properties to set on the visitor. (optional) You can also update these propertie
       #

data/lib/oursprivacy_ingest/models/visitor_upsert_params.rb

@@ -34,17 +34,19 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute email
-      #   The email address of a user. We will associate this event with the user or
-      #   create a user. Used for lookup if externalId and userId are not included in the
-      #   request.
+      #   The email address of a user. Used as a fallback lookup when neither userId nor
+      #   externalId is provided. We search your account for a visitor with this email and
+      #   attach the event to them. If no match is found, a new visitor is created.
       #
       #   @return [String, nil]
       optional :email, String, nil?: true
 
       # @!attribute external_id
-      #   The externalId (the ID in your system) of a user. We will associate this event
-      #   with the user or create a user. If included in the request, email lookup is
-      #   ignored.
+      #   Your system's unique identifier for this user. We search your account for an
+      #   existing visitor with this externalId and attach the event to them (resolving to
+      #   their Ours Visitor ID). If no match is found, a new visitor is created. When
+      #   present, email lookup is skipped. If you also have the userId from cookies or
+      #   local storage, send both — it removes the lookup round-trip.
       #
       #   @return [String, nil]
       optional :external_id, String, api_name: :externalId, nil?: true
@@ -61,9 +63,10 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute user_id
-      #   The Ours user id stored in local storage and cookies on your web properties. If
-      #   userId is included in the request, we do not lookup the user by email or
-      #   externalId.
+      #   The Ours Visitor ID stored in local storage and cookies on your web properties.
+      #   When present, this is used directly — no lookup by externalId or email is
+      #   performed. If you have both a userId and an externalId, send both so the event
+      #   is attached to the right visitor without any lookup overhead.
       #
       #   @return [String, nil]
       optional :user_id, String, api_name: :userId, nil?: true
@@ -78,13 +81,13 @@ module OursprivacyIngest
       #
       #   @param default_properties [OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      #   @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
-      #   @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       #   @param identity_context [OursprivacyIngest::Models::VisitorUpsertParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
-      #   @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      #   @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       #   @param request_options [OursprivacyIngest::RequestOptions, Hash{Symbol=>Object}]
 

data/lib/oursprivacy_ingest/resources/track.rb

@@ -6,10 +6,12 @@ module OursprivacyIngest
       # Some parameter documentations has been truncated, see
       # {OursprivacyIngest::Models::TrackEventParams} for more details.
       #
-      # Track events from your server. Please include at least one of: userId,
-      # externalId, or email. These properties help us associate events with existing
-      # users. For top-level visitor properties: null clears the existing value, while
-      # undefined, omitted fields, and empty strings are ignored. For entries inside
+      # Track events from your server. Include at least one of userId, externalId, or
+      # email so the event can be associated with a visitor. Identity resolution runs in
+      # priority order: userId (direct, no lookup) → externalId (lookup by your ID) →
+      # email (fallback lookup). If you know both userId and externalId, send both. For
+      # top-level visitor properties: null clears the existing value, while undefined,
+      # omitted fields, and empty strings are ignored. For entries inside
       # custom_properties: null, undefined, and empty strings are all ignored
       # (custom_properties use merge semantics). See
       # https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.
@@ -22,19 +24,19 @@ module OursprivacyIngest
       #
       # @param default_properties [OursprivacyIngest::Models::TrackEventParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      # @param distinct_id [String, nil] A unique identifier for the event. This helps prevent duplicate events.
+      # @param distinct_id [String, nil] A unique identifier for this event used for deduplication. Highly recommended —
       #
-      # @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      # @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
       # @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
       #
-      # @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      # @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       # @param identity_context [OursprivacyIngest::Models::TrackEventParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
       # @param time [Float, nil] The time at which the event occurred in milliseconds since UTC epoch. The time m
       #
-      # @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      # @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       # @param user_properties [OursprivacyIngest::Models::TrackEventParams::UserProperties, nil] Properties to set on the visitor. (optional) You can also update these propertie
       #

data/lib/oursprivacy_ingest/resources/visitor.rb

@@ -6,12 +6,15 @@ module OursprivacyIngest
       # Some parameter documentations has been truncated, see
       # {OursprivacyIngest::Models::VisitorUpsertParams} for more details.
       #
-      # Define visitor properties on an existing visitor or create a new visitor. This
-      # fires a $identify event, making the call visible in the event stream. For
-      # top-level visitor properties: null clears the existing value, while undefined,
-      # omitted fields, and empty strings are ignored. For entries inside
-      # custom_properties: null, undefined, and empty strings are all ignored
-      # (custom_properties use merge semantics). See
+      # Set or update properties on an existing visitor, or create a new visitor if no
+      # match is found. This fires a $identify event, making the call visible in the
+      # event stream. Identity resolution runs in priority order: userId (direct, no
+      # lookup) → externalId (lookup by your ID) → email (fallback lookup). When a
+      # visitor is found, their Ours Visitor ID is used going forward so all future
+      # events are attached to the same profile. For top-level visitor properties: null
+      # clears the existing value, while undefined, omitted fields, and empty strings
+      # are ignored. For entries inside custom_properties: null, undefined, and empty
+      # strings are all ignored (custom_properties use merge semantics). See
       # https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.
       #
       # @overload upsert(token:, user_properties:, default_properties: nil, email: nil, external_id: nil, identity_context: nil, user_id: nil, request_options: {})
@@ -22,13 +25,13 @@ module OursprivacyIngest
       #
       # @param default_properties [OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      # @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      # @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
-      # @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      # @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       # @param identity_context [OursprivacyIngest::Models::VisitorUpsertParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
-      # @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      # @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       # @param request_options [OursprivacyIngest::RequestOptions, Hash{Symbol=>Object}, nil]
       #

data/lib/oursprivacy_ingest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OursprivacyIngest
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/rbi/oursprivacy_ingest/models/batch_create_params.rbi

@@ -59,7 +59,10 @@ module OursprivacyIngest
             )
           end
 
-        # A unique identifier for the event. This helps prevent duplicate events.
+        # A unique identifier for this event used for deduplication. Highly recommended —
+        # if omitted, Ours will generate one for you, but supplying your own gives you
+        # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+        # internal order ID).
         sig { returns(String) }
         attr_accessor :distinct_id
 
@@ -89,9 +92,9 @@ module OursprivacyIngest
         end
         attr_writer :default_properties
 
-        # The email address of a user. We will associate this event with the user or
-        # create a user. Used for lookup if externalId and userId are not included in the
-        # request.
+        # The email address of a user. Used as a fallback lookup when neither userId nor
+        # externalId is provided. We search your account for a visitor with this email and
+        # attach the event to them. If no match is found, a new visitor is created.
         sig { returns(T.nilable(String)) }
         attr_accessor :email
 
@@ -99,9 +102,11 @@ module OursprivacyIngest
         sig { returns(T.nilable(T::Hash[Symbol, T.nilable(String)])) }
         attr_accessor :event_properties
 
-        # The externalId (the ID in your system) of a user. We will associate this event
-        # with the user or create a user. If included in the request, email lookup is
-        # ignored.
+        # Your system's unique identifier for this user. We search your account for an
+        # existing visitor with this externalId and attach the event to them (resolving to
+        # their Ours Visitor ID). If no match is found, a new visitor is created. When
+        # present, email lookup is skipped. If you also have the userId from cookies or
+        # local storage, send both — it removes the lookup round-trip.
         sig { returns(T.nilable(String)) }
         attr_accessor :external_id
 
@@ -132,9 +137,10 @@ module OursprivacyIngest
         sig { returns(T.nilable(Float)) }
         attr_accessor :time
 
-        # The Ours user id stored in local storage and cookies on your web properties. If
-        # userId is included in the request, we do not lookup the user by email or
-        # externalId.
+        # The Ours Visitor ID stored in local storage and cookies on your web properties.
+        # When present, this is used directly — no lookup by externalId or email is
+        # performed. If you have both a userId and an externalId, send both so the event
+        # is attached to the right visitor without any lookup overhead.
         sig { returns(T.nilable(String)) }
         attr_accessor :user_id
 
@@ -183,7 +189,10 @@ module OursprivacyIngest
           ).returns(T.attached_class)
         end
         def self.new(
-          # A unique identifier for the event. This helps prevent duplicate events.
+          # A unique identifier for this event used for deduplication. Highly recommended —
+          # if omitted, Ours will generate one for you, but supplying your own gives you
+          # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+          # internal order ID).
           distinct_id:,
           # The name of the event you're tracking. This must be whitelisted in the Ours
           # dashboard.
@@ -191,15 +200,17 @@ module OursprivacyIngest
           # These properties are used throughout the Ours app to pass known values onto
           # destinations
           default_properties: nil,
-          # The email address of a user. We will associate this event with the user or
-          # create a user. Used for lookup if externalId and userId are not included in the
-          # request.
+          # The email address of a user. Used as a fallback lookup when neither userId nor
+          # externalId is provided. We search your account for a visitor with this email and
+          # attach the event to them. If no match is found, a new visitor is created.
           email: nil,
           # Any additional event properties you want to pass along.
           event_properties: nil,
-          # The externalId (the ID in your system) of a user. We will associate this event
-          # with the user or create a user. If included in the request, email lookup is
-          # ignored.
+          # Your system's unique identifier for this user. We search your account for an
+          # existing visitor with this externalId and attach the event to them (resolving to
+          # their Ours Visitor ID). If no match is found, a new visitor is created. When
+          # present, email lookup is skipped. If you also have the userId from cookies or
+          # local storage, send both — it removes the lookup round-trip.
           external_id: nil,
           # End-user network context for server-side calls. Required for probabilistic
           # identity resolution when the caller is a backend server rather than an end-user
@@ -208,9 +219,10 @@ module OursprivacyIngest
           # The time at which the event occurred in milliseconds since UTC epoch. The time
           # must be in the past and within the last 7 days.
           time: nil,
-          # The Ours user id stored in local storage and cookies on your web properties. If
-          # userId is included in the request, we do not lookup the user by email or
-          # externalId.
+          # The Ours Visitor ID stored in local storage and cookies on your web properties.
+          # When present, this is used directly — no lookup by externalId or email is
+          # performed. If you have both a userId and an externalId, send both so the event
+          # is attached to the right visitor without any lookup overhead.
           user_id: nil,
           # Properties to set on the visitor. (optional) You can also update these
           # properties via the identify endpoint.

data/rbi/oursprivacy_ingest/models/track_event_params.rbi

@@ -42,13 +42,16 @@ module OursprivacyIngest
       end
       attr_writer :default_properties
 
-      # A unique identifier for the event. This helps prevent duplicate events.
+      # A unique identifier for this event used for deduplication. Highly recommended —
+      # if omitted, Ours will generate one for you, but supplying your own gives you
+      # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+      # internal order ID).
       sig { returns(T.nilable(String)) }
       attr_accessor :distinct_id
 
-      # The email address of a user. We will associate this event with the user or
-      # create a user. Used for lookup if externalId and userId are not included in the
-      # request.
+      # The email address of a user. Used as a fallback lookup when neither userId nor
+      # externalId is provided. We search your account for a visitor with this email and
+      # attach the event to them. If no match is found, a new visitor is created.
       sig { returns(T.nilable(String)) }
       attr_accessor :email
 
@@ -56,9 +59,11 @@ module OursprivacyIngest
       sig { returns(T.nilable(T::Hash[Symbol, T.nilable(String)])) }
       attr_accessor :event_properties
 
-      # The externalId (the ID in your system) of a user. We will associate this event
-      # with the user or create a user. If included in the request, email lookup is
-      # ignored.
+      # Your system's unique identifier for this user. We search your account for an
+      # existing visitor with this externalId and attach the event to them (resolving to
+      # their Ours Visitor ID). If no match is found, a new visitor is created. When
+      # present, email lookup is skipped. If you also have the userId from cookies or
+      # local storage, send both — it removes the lookup round-trip.
       sig { returns(T.nilable(String)) }
       attr_accessor :external_id
 
@@ -85,9 +90,10 @@ module OursprivacyIngest
       sig { returns(T.nilable(Float)) }
       attr_accessor :time
 
-      # The Ours user id stored in local storage and cookies on your web properties. If
-      # userId is included in the request, we do not lookup the user by email or
-      # externalId.
+      # The Ours Visitor ID stored in local storage and cookies on your web properties.
+      # When present, this is used directly — no lookup by externalId or email is
+      # performed. If you have both a userId and an externalId, send both so the event
+      # is attached to the right visitor without any lookup overhead.
       sig { returns(T.nilable(String)) }
       attr_accessor :user_id
 
@@ -142,17 +148,22 @@ module OursprivacyIngest
         # These properties are used throughout the Ours app to pass known values onto
         # destinations
         default_properties: nil,
-        # A unique identifier for the event. This helps prevent duplicate events.
+        # A unique identifier for this event used for deduplication. Highly recommended —
+        # if omitted, Ours will generate one for you, but supplying your own gives you
+        # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+        # internal order ID).
         distinct_id: nil,
-        # The email address of a user. We will associate this event with the user or
-        # create a user. Used for lookup if externalId and userId are not included in the
-        # request.
+        # The email address of a user. Used as a fallback lookup when neither userId nor
+        # externalId is provided. We search your account for a visitor with this email and
+        # attach the event to them. If no match is found, a new visitor is created.
         email: nil,
         # Any additional event properties you want to pass along.
         event_properties: nil,
-        # The externalId (the ID in your system) of a user. We will associate this event
-        # with the user or create a user. If included in the request, email lookup is
-        # ignored.
+        # Your system's unique identifier for this user. We search your account for an
+        # existing visitor with this externalId and attach the event to them (resolving to
+        # their Ours Visitor ID). If no match is found, a new visitor is created. When
+        # present, email lookup is skipped. If you also have the userId from cookies or
+        # local storage, send both — it removes the lookup round-trip.
         external_id: nil,
         # End-user network context for server-side calls. Required for probabilistic
         # identity resolution when the caller is a backend server rather than an end-user
@@ -161,9 +172,10 @@ module OursprivacyIngest
         # The time at which the event occurred in milliseconds since UTC epoch. The time
         # must be in the past and within the last 7 days.
         time: nil,
-        # The Ours user id stored in local storage and cookies on your web properties. If
-        # userId is included in the request, we do not lookup the user by email or
-        # externalId.
+        # The Ours Visitor ID stored in local storage and cookies on your web properties.
+        # When present, this is used directly — no lookup by externalId or email is
+        # performed. If you have both a userId and an externalId, send both so the event
+        # is attached to the right visitor without any lookup overhead.
         user_id: nil,
         # Properties to set on the visitor. (optional) You can also update these
         # properties via the identify endpoint.

data/rbi/oursprivacy_ingest/models/visitor_upsert_params.rbi

@@ -51,15 +51,17 @@ module OursprivacyIngest
       end
       attr_writer :default_properties
 
-      # The email address of a user. We will associate this event with the user or
-      # create a user. Used for lookup if externalId and userId are not included in the
-      # request.
+      # The email address of a user. Used as a fallback lookup when neither userId nor
+      # externalId is provided. We search your account for a visitor with this email and
+      # attach the event to them. If no match is found, a new visitor is created.
       sig { returns(T.nilable(String)) }
       attr_accessor :email
 
-      # The externalId (the ID in your system) of a user. We will associate this event
-      # with the user or create a user. If included in the request, email lookup is
-      # ignored.
+      # Your system's unique identifier for this user. We search your account for an
+      # existing visitor with this externalId and attach the event to them (resolving to
+      # their Ours Visitor ID). If no match is found, a new visitor is created. When
+      # present, email lookup is skipped. If you also have the userId from cookies or
+      # local storage, send both — it removes the lookup round-trip.
       sig { returns(T.nilable(String)) }
       attr_accessor :external_id
 
@@ -83,9 +85,10 @@ module OursprivacyIngest
       end
       attr_writer :identity_context
 
-      # The Ours user id stored in local storage and cookies on your web properties. If
-      # userId is included in the request, we do not lookup the user by email or
-      # externalId.
+      # The Ours Visitor ID stored in local storage and cookies on your web properties.
+      # When present, this is used directly — no lookup by externalId or email is
+      # performed. If you have both a userId and an externalId, send both so the event
+      # is attached to the right visitor without any lookup overhead.
       sig { returns(T.nilable(String)) }
       attr_accessor :user_id
 
@@ -118,21 +121,24 @@ module OursprivacyIngest
         # These properties are used throughout the Ours app to pass known values onto
         # destinations
         default_properties: nil,
-        # The email address of a user. We will associate this event with the user or
-        # create a user. Used for lookup if externalId and userId are not included in the
-        # request.
+        # The email address of a user. Used as a fallback lookup when neither userId nor
+        # externalId is provided. We search your account for a visitor with this email and
+        # attach the event to them. If no match is found, a new visitor is created.
         email: nil,
-        # The externalId (the ID in your system) of a user. We will associate this event
-        # with the user or create a user. If included in the request, email lookup is
-        # ignored.
+        # Your system's unique identifier for this user. We search your account for an
+        # existing visitor with this externalId and attach the event to them (resolving to
+        # their Ours Visitor ID). If no match is found, a new visitor is created. When
+        # present, email lookup is skipped. If you also have the userId from cookies or
+        # local storage, send both — it removes the lookup round-trip.
         external_id: nil,
         # End-user network context for server-side calls. Required for probabilistic
         # identity resolution when the caller is a backend server rather than an end-user
         # browser.
         identity_context: nil,
-        # The Ours user id stored in local storage and cookies on your web properties. If
-        # userId is included in the request, we do not lookup the user by email or
-        # externalId.
+        # The Ours Visitor ID stored in local storage and cookies on your web properties.
+        # When present, this is used directly — no lookup by externalId or email is
+        # performed. If you have both a userId and an externalId, send both so the event
+        # is attached to the right visitor without any lookup overhead.
         user_id: nil,
         request_options: {}
       )

data/rbi/oursprivacy_ingest/resources/track.rbi

@@ -3,10 +3,12 @@
 module OursprivacyIngest
   module Resources
     class Track
-      # Track events from your server. Please include at least one of: userId,
-      # externalId, or email. These properties help us associate events with existing
-      # users. For top-level visitor properties: null clears the existing value, while
-      # undefined, omitted fields, and empty strings are ignored. For entries inside
+      # Track events from your server. Include at least one of userId, externalId, or
+      # email so the event can be associated with a visitor. Identity resolution runs in
+      # priority order: userId (direct, no lookup) → externalId (lookup by your ID) →
+      # email (fallback lookup). If you know both userId and externalId, send both. For
+      # top-level visitor properties: null clears the existing value, while undefined,
+      # omitted fields, and empty strings are ignored. For entries inside
       # custom_properties: null, undefined, and empty strings are all ignored
       # (custom_properties use merge semantics). See
       # https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.
@@ -44,17 +46,22 @@ module OursprivacyIngest
         # These properties are used throughout the Ours app to pass known values onto
         # destinations
         default_properties: nil,
-        # A unique identifier for the event. This helps prevent duplicate events.
+        # A unique identifier for this event used for deduplication. Highly recommended —
+        # if omitted, Ours will generate one for you, but supplying your own gives you
+        # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+        # internal order ID).
         distinct_id: nil,
-        # The email address of a user. We will associate this event with the user or
-        # create a user. Used for lookup if externalId and userId are not included in the
-        # request.
+        # The email address of a user. Used as a fallback lookup when neither userId nor
+        # externalId is provided. We search your account for a visitor with this email and
+        # attach the event to them. If no match is found, a new visitor is created.
         email: nil,
         # Any additional event properties you want to pass along.
         event_properties: nil,
-        # The externalId (the ID in your system) of a user. We will associate this event
-        # with the user or create a user. If included in the request, email lookup is
-        # ignored.
+        # Your system's unique identifier for this user. We search your account for an
+        # existing visitor with this externalId and attach the event to them (resolving to
+        # their Ours Visitor ID). If no match is found, a new visitor is created. When
+        # present, email lookup is skipped. If you also have the userId from cookies or
+        # local storage, send both — it removes the lookup round-trip.
         external_id: nil,
         # End-user network context for server-side calls. Required for probabilistic
         # identity resolution when the caller is a backend server rather than an end-user
@@ -63,9 +70,10 @@ module OursprivacyIngest
         # The time at which the event occurred in milliseconds since UTC epoch. The time
         # must be in the past and within the last 7 days.
         time: nil,
-        # The Ours user id stored in local storage and cookies on your web properties. If
-        # userId is included in the request, we do not lookup the user by email or
-        # externalId.
+        # The Ours Visitor ID stored in local storage and cookies on your web properties.
+        # When present, this is used directly — no lookup by externalId or email is
+        # performed. If you have both a userId and an externalId, send both so the event
+        # is attached to the right visitor without any lookup overhead.
         user_id: nil,
         # Properties to set on the visitor. (optional) You can also update these
         # properties via the identify endpoint.

data/rbi/oursprivacy_ingest/resources/visitor.rbi

@@ -3,12 +3,15 @@
 module OursprivacyIngest
   module Resources
     class Visitor
-      # Define visitor properties on an existing visitor or create a new visitor. This
-      # fires a $identify event, making the call visible in the event stream. For
-      # top-level visitor properties: null clears the existing value, while undefined,
-      # omitted fields, and empty strings are ignored. For entries inside
-      # custom_properties: null, undefined, and empty strings are all ignored
-      # (custom_properties use merge semantics). See
+      # Set or update properties on an existing visitor, or create a new visitor if no
+      # match is found. This fires a $identify event, making the call visible in the
+      # event stream. Identity resolution runs in priority order: userId (direct, no
+      # lookup) → externalId (lookup by your ID) → email (fallback lookup). When a
+      # visitor is found, their Ours Visitor ID is used going forward so all future
+      # events are attached to the same profile. For top-level visitor properties: null
+      # clears the existing value, while undefined, omitted fields, and empty strings
+      # are ignored. For entries inside custom_properties: null, undefined, and empty
+      # strings are all ignored (custom_properties use merge semantics). See
       # https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.
       sig do
         params(
@@ -39,21 +42,24 @@ module OursprivacyIngest
         # These properties are used throughout the Ours app to pass known values onto
         # destinations
         default_properties: nil,
-        # The email address of a user. We will associate this event with the user or
-        # create a user. Used for lookup if externalId and userId are not included in the
-        # request.
+        # The email address of a user. Used as a fallback lookup when neither userId nor
+        # externalId is provided. We search your account for a visitor with this email and
+        # attach the event to them. If no match is found, a new visitor is created.
         email: nil,
-        # The externalId (the ID in your system) of a user. We will associate this event
-        # with the user or create a user. If included in the request, email lookup is
-        # ignored.
+        # Your system's unique identifier for this user. We search your account for an
+        # existing visitor with this externalId and attach the event to them (resolving to
+        # their Ours Visitor ID). If no match is found, a new visitor is created. When
+        # present, email lookup is skipped. If you also have the userId from cookies or
+        # local storage, send both — it removes the lookup round-trip.
         external_id: nil,
         # End-user network context for server-side calls. Required for probabilistic
         # identity resolution when the caller is a backend server rather than an end-user
         # browser.
         identity_context: nil,
-        # The Ours user id stored in local storage and cookies on your web properties. If
-        # userId is included in the request, we do not lookup the user by email or
-        # externalId.
+        # The Ours Visitor ID stored in local storage and cookies on your web properties.
+        # When present, this is used directly — no lookup by externalId or email is
+        # performed. If you have both a userId and an externalId, send both so the event
+        # is attached to the right visitor without any lookup overhead.
         user_id: nil,
         request_options: {}
       )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oursprivacy-ingest
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Ours Privacy