Sending events to Alvie | Learning Center

To benefit from Alvie’s Enhanced signals feature, which receives, transforms, and loads event-specific information to different platforms, events need to be sent to Alvie in the proper format and manner.

Please pay attention to the event sending guidelines. This will help ensure that all required data is received in the proper format, forming the basis for specific transformations.

General requirements for event sending

Enhanced signals receives events via HTTP POST requests with the event payload formatted as JSON in the body of the request. Thus, any site tag or back-end system can send events to Enhanced signals.

1. Inbound events should be sent as HTTP POST to the service URL: https://enhanced-signals.alvie.tech.

2. Query parameters:

config_id (required): A configuration ID is generated when a new Enhanced signals configuration is created. Simply check the link in the browser to obtain the correct config_id: https://dashboard.alvie.io/enhanced-signals/5082701814038528/dashboard?clientId=5127552620298240. The part in bold is the exact config_id required.
dry_run (optional): This parameter is used for testing the event setup and output. It is highly recommended to test an implementation with a dry run parameter before going live. You can learn more about this parameter here.

3. Event data should be formatted in the JSON body of the HTTP POST request.

Check these examples:

Example of an event JSON body

{   
  "client_id": "1713917661.1645021190",   
  "user_id": "",   
  "timestamp_micros": "",   
  "non_personalized_ads": false,   
  "user_properties": {     
     "nth_purchase": { "value": "5" },     
     "user_lang": { "language": "swedish" },   
 },   
  "cookies": "CookieConsent={...",   
  "user_data": {         
     "sha256_email_address": [             
       "[email protected]",             
       "[email protected]",             
       "[email protected]",             
       "[email protected]",             
       "[email protected]" ],         
     "sha256_phone_number": [             
       "+467000000000"         ],        
     "address": [             
          {                 
           "sha256_first_name": "Test",                 
           "sha256_street": "Test Street",                
           "city": "TestCity",                 
           "region": "TestRegion",                 
           "postal_code": "44422",                 
           "country": "country1"             
          },             
          {                 
            "country": "country2"             
          },             
          {                 
            "country": "country3"             
          },             
          {                
            "country": "country4"             
          }         
       ]     
   },     
    "consent": {         
      "ad_user_data": "GRANTED",         
      "ad_personalization": "GRANTED"    
   },   
 "event":     
  {       
  "name": "purchase",       
  "params": {         
     "engagement_time_msec": "500",         
     "session_id": "3335021123",         
     "currency": "SEK",         
     "market": “se”,         
     "transaction_id": "T_12345",         
     "value": 1299,         
     "affiliation": "Google Store",         
     "coupon": "SUMMER_FUN",         
     "customer_type": "returning",         
     "user_defined": "high_value_customer",         
     "shipping": 99,         
     "tax": 259.8,         
     "page_location": "https://clientx.com/thank-you?order=T_12345",                        "items": [           
   {             
    "item_id": "SKU_12345",             
    "item_name": "Stan and Friends Tee",             
    "discount": 2.22,             
    "item_brand": "Google",             
    "item_category": "Apparel",             
    "item_variant": "green",             "
     quantity": 1,          
   },           
   {             
    "item_id": "SKU_45678",             
    "item_name": "Stan and Friends Hoodie",             
    "discount": 2.22,             
    "item_brand": "Google",             
    "item_category": "Apparel",             
    "item_variant": "black",             
    "quantity": 2,          
   },        
 ],      
 },   
 } 
}

Required event values

config_id
event data (JSON body in an HTTP POST request)

client_id
event.name
event.params.session_id
event.params.currency
event.params.transaction_id
event.params.value
event.params.market
event.params.page_location
event.params.items[*].item_id
event.params.items[*].item_name
event.params.items[*].price
event.params.items[*].quantity
event.params.items[*].item_id

Specific requirements for the events sending

While the Google Analytics 4: GTAG and Google Analytics 4: Firebase targets have only the standard requirements for sending events, as explained above, some targets have specific additional requirements for sending events.

Google Tag Manager: Server-side

For the Google Tag Manager: Server-side target, If you include a 'cookies' parameter when sending the hit from the front-end client to Enhanced signals, Enhanced signals will attempt to parse it and return a JSON representation of those values in the request to the sGTM container.

Google Ads: Click conversion

For the Google Ads: Click conversions target, the following additional parameters are required in the inbound events being sent to Enhanced signals.

For events being sent via GTM, they can be added to the 'Enhanced signals settings variable' described in this guide.

1. gads_id: Google Ads click ID (gclid/gbraid/wbraid) (required)

For example: Cj0KCABC4rfhBRC1ARIsAFHqKKr2fKL_jfh6khshobNZq3yEZ8HPmN3I12GHeXK4J-DmGes-YqOSVSIaAkDNEALw_wcB

Added at the path event.params.gads_id.

2. conversion_date_time: Conversion date time (required)

The date and time of the conversion should be after the click time. The format is ‘yyyy-mm-dd hh:mm:ss+|-hh:mm’.

For example: 2023-01-01 12:32:45-08:00

Added at the path event.params.conversion_date_time.

3. consent: Consent (required)

The consent setting for the event contains two parameters:

ad_user_data: value can be either ‘granted’ or ‘denied’,
ad_personalization: value can be either ‘granted’ or ‘denied’.

4. gads_tracking_type: Gads Tracking type (gclid, gbraid, or wbriad) (optional)

The default value is ‘gclid’.

Added at the path event.params.gads_tracking_type.

5. Below is a complete example of an event payload with the added values:

{   
   "client_id": "99999",   
   "non_personalized_ads": false,   
   "user_properties": {     
     "returning":  {"value":  true},     
     "user_group": {"value":  "good_vibes"}   
   },   
   "consent": {     
     "ad_user_data": "GRANTED",     
     "ad_personalization": "DENIED"   
   },   
   "event": {     
     "name": "purchase",    
     "params": {       
       "conversion_date_time": "2021-01-01 12:32:45-08:00",                     "gads_id": "12345",       
       "currency": "NOK",       
       "transaction_id": "T_12345",      
       "value": 12.21,       
       "affiliation": "Google Store",     
       "coupon": "SUMMER_FUN",      
       "shipping": 3.33,      
       "tax": 1.11,      
       "market": "se",       
       "page_location": "https://domain.com/thank-you",              "unmatched_product_ids": ["xxx", "yyy"],       
       "user_agent": "test",      
       "items": [         
          {          
          "item_id": "1000244002",           
          "item_name": "pom-pomps",           
          "price": 100.00,           
          "quantity": 2,           
          "affiliation": "Google Store",           
          "coupon": "SUMMER_FUN",           
          "item_brand": "Gucci",           
          "item_category": "dog high heels",           
          "item_variant": "pink",           
          "cost": 10,           
          "lookup_key": "top_customer"      
          }       
        ]     
      }   
    },   
"cookies": "CookieConsent={stamp:%275Hw6D9avcDs9V8nFhr7GivK0fJGy6jWyMlSWafBKmXR1rei5R91Myw==%27%2Cnecessary:true%2Cpreferences:true%2Cstatistics:true%2Cmarketing:true%2Cmethod:%27explicit%27%2Cver:1%2Cutc:1671635725480%2Cregion:%27se%27}; _fbp=fb.1.1671635726154.654125160; _gid=GA1.2.1461252865.1673970186; __TAG_ASSISTANT=x; _gat_UA-191799530-2=1; _gat_UA-191799530-1=1; _gat_UA-191799530-3=1; _ga_KW4EB2YMV7=GS1.1.1674115360.13.0.1674115360.0.0.0; _ga=GA1.1.944598999.1671635723; _ga_KR6CH35DW0=GS1.1.1674115360.13.0.1674115360.60.0.0" 
}

Facebook: Conversion API

For the Facebook: Conversion API , at least one of the following parameters is required in the inbound event payload being sent to Enhanced signals for them to be accepted by the Conversion API endpoint

For events being sent via GTM, they can be added to the 'Enhanced signals settings variable' described in this guide.

1. event.params.fbc: Facebook click ID.

The fbc value (found in the _fbc cookie). The variable should return undefined if the Facebook click ID is not available.

2. event.params.fbp: Facebook browser ID.

The fbp value (found in _fbp cookie). The variable should return undefined if the Facebook browser ID is not available.

3. user_data.sha256_email_address: Email Address.

The users email address as either:

A regular string, '[email protected]'. Enhanced signals will hash this value using SHA256 algorithm before it reaches Facebook.
Hashed using SHA256 algorithm on lowercase string with no white space, encode with hex string format.

Use an array if supplying multiple email addresses.

4. user_data.sha256_phone_number: Phone number.

The users phone number as either:

A regular integer, '+461234567890'. Enhanced signals will hash this value using SHA256 algorithm before it reaches Facebook.
Hashed using SHA256 algorithm and encoded with hex string format. Add “+” prefix and remove all non digits before hashing.

Use an array if supplying multiple phone numbers.

5. user_data.address.sha256_first_name: First name.

The users first name as either:

A regular string, 'John'. Enhanced signals will hash this value using SHA256 algorithm before it reaches Facebook.
Hashed using SHA256 algorithm and encoded with hex string format. Remove any digits, symbols characters, leading and trailing spaces and make it lowercase before hashing.

6. user_data.address.sha256_last_name: Last name.

The users last name as either:

A regular string, 'Doe'. Enhanced signals will hash this value using SHA256 algorithm before it reaches Facebook.
Hashed using SHA256 algorithm and encoded with hex string format. Remove any digits, symbols characters, leading and trailing spaces and make it lowercase before hashing.

Optional parameters

At least one of the following parameters is required in the inbound event payload:

1. event.params.content_type: Content type.

This should be set to either 'product' or 'product_group':

Use 'product' if the IDs of the items in the events have unique SKUs, including variations in colour and size.
Use 'product_group' if the IDs of the items in the events represent a group of unique products without variations in size or colour.

If the parameter is not set, it will default to 'product'. You can learn more about this parameter here.

2. user_data.address.sha256_street: Street.

The users street address as either:

A regular string, ‘test street 123’. Enhanced signals will hash this value using SHA256 algorithm before it reaches Facebook.
Hashed using SHA256 algorithm and encoded with hex string format. Remove any symbols characters, leading and trailing spaces and make it lowercase before hashing.

3. user_data.address.city: City

A regular string, e.g., 'stockholm'. Convert to lowercase and remove any leading or trailing spaces.

4. user_data.address.region: Region

A regular string, e.g., 'uppland'. Convert to lowercase and remove any leading or trailing spaces.

5. user_data.address.postal_code: Postal code

A regular integer, e.g., 12345.

6. user_data.address.country: Country

A regular string, e.g., 'SE'. Use the lowercase, 2-letter country codes in ISO 3166-1 alpha-2.

Below is a complete example of a Facebook: Conversion API event payload:

{     
     "client_id": "2066134824.1716535961",     
     "timestamp_micros": 1717567692792000,     
     "non_personalized_ads": false,     
     "user_data": {          
        "sha256_email_address": [             
           "[email protected]",             
           "[email protected]",             
           "[email protected]",            
           "[email protected]",           
           "[email protected]"         
         ],         
        "sha256_phone_number": [             
          "+467000000000"         
         ],         
         "address": [             
            {                 
              "sha256_first_name": "Test",                                             "sha256_street": "Test Street",                 
              "city": "TestCity",                
              "region": "TestRegion",                
              "postal_code": "44422",                 
              "country": "country1"             
            },             
            {                 
              "country": "country2"           
            },             
            {                 
              "country": "country3"            
            },            
            {               
              "country": "country4"             
            }         
         ]     
      },     
      "consent": {         
        "ad_user_data": "GRANTED",         
        "ad_personalization": "GRANTED"     
      },    
      "event": {         
        "name": "purchase",       
        "params": {             
        "market": "default",           
        "session_id": "1717566251",           
        "page_location": "https://test-site-xyz.com/ecommerce.html?testES=true&gtm_debug=1717567682452",                          "engagement_time_msec": 1500,            
        "currency": "sek",             
        "transaction_id": "TR_GA4_100260",          
        "value": 59.89,             
        "affiliation": "Online Store",            
        "coupon": "SUMMER_SALE",            
        "shipping": 5.99,             
        "tax": 4.9,            
        "items": [                 
           {                     
           "item_id": "12345",                     
           "item_name": "Triblend Android T-Shirt",                                "item_brand": "Google",                     
           "item_variant": "Gray",                     
           "item_category": "Apparel",                     
           "quantity": 1,                   
           "price": 15.25                
           },                 
           {                     
           "item_id": "67890",                     
           "item_name": "Donut Friday Scented T-Shirt",                                "item_brand": "Google",                     
           "item_variant": "Black",                     
           "item_category": "Apparel",                     
           "quantity": 1,                     
           "price": 33.75                 
           }             
      ],             
      "debug_mode": true,             
      "fbp": "fbp.123.123",             
      "fbc": "fbc.123.123",             
      "content_type": "product"         
   }     
 } 
}

As soon as you finish setting up event sending, we encourage you to test and validate the data setup and output.

Item lookup value transformation

Send events using Google Tag Manager

How to prepare targets to receive information from Enhanced signals

Manual data validation for specific targets

How to set up the Enhanced Signals configuration