oursprivacy-ingest 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ed1b63854906efe0f462b08eaf8cb9de0ff4a4586e13ce25159e54371939947
-  data.tar.gz: 0531b08a511ed70b76b42a47d2541dfdf11fc388cce6b0a03f53f8f8017d3cde
+  metadata.gz: 58ab60818e804371f1f03601d65833bc11e8f5ed9698706d889181bb783b687f
+  data.tar.gz: 5857962996b22619663cde42083aa722f98be269735473771343811d30fd9821
 SHA512:
-  metadata.gz: e629ea80c262196d7cf71ccf58a9ed7dcbc6ea633e7c89863a344dbc8dd24c48dcd58ce18881842989aa85986c62b3c8ff1d393b88eaec7a43444b4dc0dce7aa
-  data.tar.gz: fca70c8d6c4c831dd2a624d409e244ebabe7ed4865de14b55aad2c5b9e4f3152d7c7ed5dde54e0f7507fa6a1a73fb97e96dbe9ffa677940eb3b65c3e9719bafe
+  metadata.gz: bde8ec9eb06b0e56ef71dad7e28cb1ba5525806890af099a08006617247ba9e2ae3312fd74a9e4f255e1e1146ea0262f387e142994e5683a4398cd37739236c1
+  data.tar.gz: 61803bff65a065a1c8272195597c00840090a1289744da95fd2657b814b499a920c0b158efd2df860f6de795ad25a7e534c5883606fbf92727b8848e64e2e922

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.7.0 (2026-05-08)
+
+Full Changelog: [v1.6.0...v1.7.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.6.0...v1.7.0)
+
+### Features
+
+* **api:** api update ([356be54](https://github.com/with-ours/ingest-sdk-ruby/commit/356be5482b0ac292331685dba21a31e91a0f9d02))
+
+## 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.7.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,28 +122,35 @@ 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
 
         # @see OursprivacyIngest::Models::BatchCreateParams::Event#default_properties
         class DefaultProperties < OursprivacyIngest::Internal::Type::BaseModel
+          # @!attribute _ef_transaction_id
+          #   The Everflow affiliate Click (Transaction) ID, captured from the
+          #   `_ef_transaction_id` URL parameter. Ex: ef_click_abc123
+          #
+          #   @return [String, nil]
+          optional :_ef_transaction_id, String, nil?: true
+
           # @!attribute active_duration
           #   The active time in milliseconds that the user had this tab active
           #
@@ -577,7 +590,7 @@ module OursprivacyIngest
           #   @return [Boolean, nil]
           optional :webview, OursprivacyIngest::Internal::Type::Boolean, nil?: true
 
-          # @!method initialize(active_duration: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, browser_language: nil, browser_name: nil, browser_version: nil, campaign_id: nil, clickid: nil, clid: nil, cpu_architecture: nil, current_url: nil, dclid: nil, device_model: nil, device_type: nil, device_vendor: nil, duration: nil, encoding: nil, engine_name: nil, engine_version: nil, epik: nil, fbc: nil, fbclid: nil, fbp: nil, fv: nil, gad_source: nil, gbraid: nil, gclid: nil, host: nil, iframe: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, new_s: nil, os_name: nil, os_version: nil, page_hash: nil, pathname: nil, qclid: nil, rdt_cid: nil, received_at: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, screen_height: nil, screen_width: nil, session_count: nil, sid: nil, sr: nil, title: nil, ttclid: nil, twclid: nil, uafvl: nil, user_agent: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, version: nil, wbraid: nil, webview: nil)
+          # @!method initialize(_ef_transaction_id: nil, active_duration: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, browser_language: nil, browser_name: nil, browser_version: nil, campaign_id: nil, clickid: nil, clid: nil, cpu_architecture: nil, current_url: nil, dclid: nil, device_model: nil, device_type: nil, device_vendor: nil, duration: nil, encoding: nil, engine_name: nil, engine_version: nil, epik: nil, fbc: nil, fbclid: nil, fbp: nil, fv: nil, gad_source: nil, gbraid: nil, gclid: nil, host: nil, iframe: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, new_s: nil, os_name: nil, os_version: nil, page_hash: nil, pathname: nil, qclid: nil, rdt_cid: nil, received_at: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, screen_height: nil, screen_width: nil, session_count: nil, sid: nil, sr: nil, title: nil, ttclid: nil, twclid: nil, uafvl: nil, user_agent: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, version: nil, wbraid: nil, webview: nil)
           #   Some parameter documentations has been truncated, see
           #   {OursprivacyIngest::Models::BatchCreateParams::Event::DefaultProperties} for
           #   more details.
@@ -585,6 +598,9 @@ module OursprivacyIngest
           #   These properties are used throughout the Ours app to pass known values onto
           #   destinations
           #
+          #   @param _ef_transaction_id [String, nil] The Everflow affiliate Click (Transaction) ID, captured from the
+          #   `\_ef_transactio
+          #
           #   @param active_duration [Float, nil] The active time in milliseconds that the user had this tab active
           #
           #   @param ad_id [String, nil] The ad id for detected in the session. This is set by the web sdk automatically.
@@ -756,6 +772,11 @@ module OursprivacyIngest
 
         # @see OursprivacyIngest::Models::BatchCreateParams::Event#user_properties
         class UserProperties < OursprivacyIngest::Internal::Type::BaseModel
+          # @!attribute _ef_transaction_id
+          #
+          #   @return [String, nil]
+          optional :_ef_transaction_id, String, nil?: true
+
           # @!attribute ad_id
           #
           #   @return [String, nil]
@@ -1049,10 +1070,12 @@ module OursprivacyIngest
           #   @return [String, nil]
           optional :zip, String, nil?: true
 
-          # @!method initialize(ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, campaign_id: nil, city: nil, clickid: nil, clid: nil, company_name: nil, consent: nil, country: nil, custom_properties: nil, date_of_birth: nil, dclid: nil, email: nil, epik: nil, external_id: nil, fbc: nil, fbclid: nil, fbp: nil, first_name: nil, gad_source: nil, gbraid: nil, gclid: nil, gender: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, job_title: nil, last_name: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, phone_number: nil, qclid: nil, rdt_cid: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, sid: nil, state: nil, ttclid: nil, twclid: nil, user_agent: nil, user_agent_full_list: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, wbraid: nil, zip: nil)
+          # @!method initialize(_ef_transaction_id: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, campaign_id: nil, city: nil, clickid: nil, clid: nil, company_name: nil, consent: nil, country: nil, custom_properties: nil, date_of_birth: nil, dclid: nil, email: nil, epik: nil, external_id: nil, fbc: nil, fbclid: nil, fbp: nil, first_name: nil, gad_source: nil, gbraid: nil, gclid: nil, gender: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, job_title: nil, last_name: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, phone_number: nil, qclid: nil, rdt_cid: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, sid: nil, state: nil, ttclid: nil, twclid: nil, user_agent: nil, user_agent_full_list: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, wbraid: nil, zip: nil)
           #   Properties to set on the visitor. (optional) You can also update these
           #   properties via the identify endpoint.
           #
+          #   @param _ef_transaction_id [String, nil]
+          #
           #   @param ad_id [String, nil]
           #
           #   @param admitad_uid [String, nil]

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,25 +113,32 @@ 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
       #
       #   @param request_options [OursprivacyIngest::RequestOptions, Hash{Symbol=>Object}]
 
       class DefaultProperties < OursprivacyIngest::Internal::Type::BaseModel
+        # @!attribute _ef_transaction_id
+        #   The Everflow affiliate Click (Transaction) ID, captured from the
+        #   `_ef_transaction_id` URL parameter. Ex: ef_click_abc123
+        #
+        #   @return [String, nil]
+        optional :_ef_transaction_id, String, nil?: true
+
         # @!attribute active_duration
         #   The active time in milliseconds that the user had this tab active
         #
@@ -565,7 +578,7 @@ module OursprivacyIngest
         #   @return [Boolean, nil]
         optional :webview, OursprivacyIngest::Internal::Type::Boolean, nil?: true
 
-        # @!method initialize(active_duration: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, browser_language: nil, browser_name: nil, browser_version: nil, campaign_id: nil, clickid: nil, clid: nil, cpu_architecture: nil, current_url: nil, dclid: nil, device_model: nil, device_type: nil, device_vendor: nil, duration: nil, encoding: nil, engine_name: nil, engine_version: nil, epik: nil, fbc: nil, fbclid: nil, fbp: nil, fv: nil, gad_source: nil, gbraid: nil, gclid: nil, host: nil, iframe: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, new_s: nil, os_name: nil, os_version: nil, page_hash: nil, pathname: nil, qclid: nil, rdt_cid: nil, received_at: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, screen_height: nil, screen_width: nil, session_count: nil, sid: nil, sr: nil, title: nil, ttclid: nil, twclid: nil, uafvl: nil, user_agent: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, version: nil, wbraid: nil, webview: nil)
+        # @!method initialize(_ef_transaction_id: nil, active_duration: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, browser_language: nil, browser_name: nil, browser_version: nil, campaign_id: nil, clickid: nil, clid: nil, cpu_architecture: nil, current_url: nil, dclid: nil, device_model: nil, device_type: nil, device_vendor: nil, duration: nil, encoding: nil, engine_name: nil, engine_version: nil, epik: nil, fbc: nil, fbclid: nil, fbp: nil, fv: nil, gad_source: nil, gbraid: nil, gclid: nil, host: nil, iframe: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, new_s: nil, os_name: nil, os_version: nil, page_hash: nil, pathname: nil, qclid: nil, rdt_cid: nil, received_at: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, screen_height: nil, screen_width: nil, session_count: nil, sid: nil, sr: nil, title: nil, ttclid: nil, twclid: nil, uafvl: nil, user_agent: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, version: nil, wbraid: nil, webview: nil)
         #   Some parameter documentations has been truncated, see
         #   {OursprivacyIngest::Models::TrackEventParams::DefaultProperties} for more
         #   details.
@@ -573,6 +586,9 @@ module OursprivacyIngest
         #   These properties are used throughout the Ours app to pass known values onto
         #   destinations
         #
+        #   @param _ef_transaction_id [String, nil] The Everflow affiliate Click (Transaction) ID, captured from the
+        #   `\_ef_transactio
+        #
         #   @param active_duration [Float, nil] The active time in milliseconds that the user had this tab active
         #
         #   @param ad_id [String, nil] The ad id for detected in the session. This is set by the web sdk automatically.
@@ -742,6 +758,11 @@ module OursprivacyIngest
       end
 
       class UserProperties < OursprivacyIngest::Internal::Type::BaseModel
+        # @!attribute _ef_transaction_id
+        #
+        #   @return [String, nil]
+        optional :_ef_transaction_id, String, nil?: true
+
         # @!attribute ad_id
         #
         #   @return [String, nil]
@@ -1033,10 +1054,12 @@ module OursprivacyIngest
         #   @return [String, nil]
         optional :zip, String, nil?: true
 
-        # @!method initialize(ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, campaign_id: nil, city: nil, clickid: nil, clid: nil, company_name: nil, consent: nil, country: nil, custom_properties: nil, date_of_birth: nil, dclid: nil, email: nil, epik: nil, external_id: nil, fbc: nil, fbclid: nil, fbp: nil, first_name: nil, gad_source: nil, gbraid: nil, gclid: nil, gender: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, job_title: nil, last_name: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, phone_number: nil, qclid: nil, rdt_cid: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, sid: nil, state: nil, ttclid: nil, twclid: nil, user_agent: nil, user_agent_full_list: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, wbraid: nil, zip: nil)
+        # @!method initialize(_ef_transaction_id: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, campaign_id: nil, city: nil, clickid: nil, clid: nil, company_name: nil, consent: nil, country: nil, custom_properties: nil, date_of_birth: nil, dclid: nil, email: nil, epik: nil, external_id: nil, fbc: nil, fbclid: nil, fbp: nil, first_name: nil, gad_source: nil, gbraid: nil, gclid: nil, gender: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, job_title: nil, last_name: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, phone_number: nil, qclid: nil, rdt_cid: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, sid: nil, state: nil, ttclid: nil, twclid: nil, user_agent: nil, user_agent_full_list: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, wbraid: nil, zip: nil)
         #   Properties to set on the visitor. (optional) You can also update these
         #   properties via the identify endpoint.
         #
+        #   @param _ef_transaction_id [String, nil]
+        #
         #   @param ad_id [String, nil]
         #
         #   @param admitad_uid [String, nil]

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,17 +81,22 @@ 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}]
 
       class UserProperties < OursprivacyIngest::Internal::Type::BaseModel
+        # @!attribute _ef_transaction_id
+        #
+        #   @return [String, nil]
+        optional :_ef_transaction_id, String, nil?: true
+
         # @!attribute ad_id
         #
         #   @return [String, nil]
@@ -380,11 +388,13 @@ module OursprivacyIngest
         #   @return [String, nil]
         optional :zip, String, nil?: true
 
-        # @!method initialize(ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, campaign_id: nil, city: nil, clickid: nil, clid: nil, company_name: nil, consent: nil, country: nil, custom_properties: nil, date_of_birth: nil, dclid: nil, email: nil, epik: nil, external_id: nil, fbc: nil, fbclid: nil, fbp: nil, first_name: nil, gad_source: nil, gbraid: nil, gclid: nil, gender: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, job_title: nil, last_name: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, phone_number: nil, qclid: nil, rdt_cid: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, sid: nil, state: nil, ttclid: nil, twclid: nil, user_agent: nil, user_agent_full_list: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, wbraid: nil, zip: nil)
+        # @!method initialize(_ef_transaction_id: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, campaign_id: nil, city: nil, clickid: nil, clid: nil, company_name: nil, consent: nil, country: nil, custom_properties: nil, date_of_birth: nil, dclid: nil, email: nil, epik: nil, external_id: nil, fbc: nil, fbclid: nil, fbp: nil, first_name: nil, gad_source: nil, gbraid: nil, gclid: nil, gender: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, job_title: nil, last_name: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, phone_number: nil, qclid: nil, rdt_cid: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, sid: nil, state: nil, ttclid: nil, twclid: nil, user_agent: nil, user_agent_full_list: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, wbraid: nil, zip: nil)
         #   User properties to associate with this user. The existing user properties will
         #   be updated. And all future events will have these properties associated with
         #   them.
         #
+        #   @param _ef_transaction_id [String, nil]
+        #
         #   @param ad_id [String, nil]
         #
         #   @param admitad_uid [String, nil]
@@ -503,6 +513,13 @@ module OursprivacyIngest
       end
 
       class DefaultProperties < OursprivacyIngest::Internal::Type::BaseModel
+        # @!attribute _ef_transaction_id
+        #   The Everflow affiliate Click (Transaction) ID, captured from the
+        #   `_ef_transaction_id` URL parameter. Ex: ef_click_abc123
+        #
+        #   @return [String, nil]
+        optional :_ef_transaction_id, String, nil?: true
+
         # @!attribute active_duration
         #   The active time in milliseconds that the user had this tab active
         #
@@ -942,7 +959,7 @@ module OursprivacyIngest
         #   @return [Boolean, nil]
         optional :webview, OursprivacyIngest::Internal::Type::Boolean, nil?: true
 
-        # @!method initialize(active_duration: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, browser_language: nil, browser_name: nil, browser_version: nil, campaign_id: nil, clickid: nil, clid: nil, cpu_architecture: nil, current_url: nil, dclid: nil, device_model: nil, device_type: nil, device_vendor: nil, duration: nil, encoding: nil, engine_name: nil, engine_version: nil, epik: nil, fbc: nil, fbclid: nil, fbp: nil, fv: nil, gad_source: nil, gbraid: nil, gclid: nil, host: nil, iframe: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, new_s: nil, os_name: nil, os_version: nil, page_hash: nil, pathname: nil, qclid: nil, rdt_cid: nil, received_at: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, screen_height: nil, screen_width: nil, session_count: nil, sid: nil, sr: nil, title: nil, ttclid: nil, twclid: nil, uafvl: nil, user_agent: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, version: nil, wbraid: nil, webview: nil)
+        # @!method initialize(_ef_transaction_id: nil, active_duration: nil, ad_id: nil, admitad_uid: nil, adset_id: nil, alart: nil, aleid: nil, axwrt: nil, basis_cid: nil, browser_language: nil, browser_name: nil, browser_version: nil, campaign_id: nil, clickid: nil, clid: nil, cpu_architecture: nil, current_url: nil, dclid: nil, device_model: nil, device_type: nil, device_vendor: nil, duration: nil, encoding: nil, engine_name: nil, engine_version: nil, epik: nil, fbc: nil, fbclid: nil, fbp: nil, fv: nil, gad_source: nil, gbraid: nil, gclid: nil, host: nil, iframe: nil, im_ref: nil, ip: nil, irclickid: nil, is_bot: nil, li_fat_id: nil, msclkid: nil, ndclid: nil, new_s: nil, os_name: nil, os_version: nil, page_hash: nil, pathname: nil, qclid: nil, rdt_cid: nil, received_at: nil, referrer: nil, referring_domain: nil, sacid: nil, sccid: nil, screen_height: nil, screen_width: nil, session_count: nil, sid: nil, sr: nil, title: nil, ttclid: nil, twclid: nil, uafvl: nil, user_agent: nil, utm_campaign: nil, utm_content: nil, utm_medium: nil, utm_name: nil, utm_source: nil, utm_term: nil, version: nil, wbraid: nil, webview: nil)
         #   Some parameter documentations has been truncated, see
         #   {OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties} for more
         #   details.
@@ -950,6 +967,9 @@ module OursprivacyIngest
         #   These properties are used throughout the Ours app to pass known values onto
         #   destinations
         #
+        #   @param _ef_transaction_id [String, nil] The Everflow affiliate Click (Transaction) ID, captured from the
+        #   `\_ef_transactio
+        #
         #   @param active_duration [Float, nil] The active time in milliseconds that the user had this tab active
         #
         #   @param ad_id [String, nil] The ad id for detected in the session. This is set by the web sdk automatically.

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.7.0"
 end