Event Data Exports

Neon provides a number of user behavior insights directly in the Console. You can also set up exports of additional analytics events for more detailed tracking. You can configure these exports via the Console.

We deliver hourly analytics events directly to your AWS S3 or Google Cloud Storage bucket in JSONL GZ format. Events are separated by environment (e.g. Sandbox, Production, Staging), ensuring accurate tracking and analysis (sample file).

This document serves as a comprehensive guide to the analytics events and their associated attributes used within our application. These events play a vital role in tracking user interactions, behaviors, and other essential metrics, enabling you to enhance the user experience and make informed, data-driven decisions.

Configuration

AWS S3

1. Set the following bucket policy on your S3 bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::171666793654:role/NeonS3Access"
            },
            "Action": [
                "s3:AbortMultipartUpload",
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::BUCKET_NAME",
                "arn:aws:s3:::BUCKET_NAME/*"
            ]
        }
    ]
}

2. Open Neon Console, and Navigate to Developer Settongs ->Analytics Exports

3. 

   Click “Add S3 Destination” and enter the Bucket Name, Region, and Path Prefix. The Path Prefix defines the folder where analytics exports will be stored. We recommend using a unique prefix per title to keep analytics data organized across multiple titles.

   

Google Cloud Storage

1. Create a new service account to give Neon access to upload to your Bucket.

2. Create a JSON key for the service account. The key will need to be exported as JSON and securely uploaded to Neon. The key is stored encrypted at rest and will only be accessed for analytics exports.

3. Configure the bucket to grant the Storage Object Admin role to the new service account.

4. Configure the export with Neon. You'll need to provide the following.

   1. JSON account key from step 2
   2. Bucket name
   3. Prefix (optional)

5. Open the Neon Console and navigate to Developer Settings -> Analytics Exports. Click “Add GCS Destination”, then enter the information obtained in Step 4.

   

Exported Files

A single gzipped JSON Lines file will be exported hourly to your bucket.

The file will be written to the following path: ${prefix}/${environment_id}/YYYY/MM/DDTHH-neon-analytics.json.gz.

• prefix: your optional prefix
• environment_id: Neon provided identifier for game + environment (e.g. Game 1 Production)
• YYYY/MM/DDTHH: date and hour (in UTC)

Event Details

Analytics events are systematically logged across our application to capture diverse player actions and behaviors. Each event provides invaluable insights into how players engage with your Neon Shop and navigate through the purchasing process. Each event object in the file will include the following top-level keys.

Event Data

• event_time: Timestamp indicating when the event occurred.
• event_type: Type of event triggered, providing context for the player action or behavior.
• event_properties: Various event-specific attributes. The possible values are specified below.
• log_version_id: Internal version identifier used to track changes in event logging schema.

Player/Session Data

Events include device and session information when available. However, this data may be unavailable or contain special server values when:

• Users are blocking tracking
• Events are server-initiated (e.g., checkout created via POST /checkout endpoint)

Device & Session Properties

• device_id: Device identifier. Returns 00000000-c57a-4f9b-afe8-3fe404dc84f5 when real device info is unavailable.
• session_id: Unique session identifier (integer). Returns -1 when no session is available.

Browser Information: (Parsed from user agent, null when unavailable)

• os_name: Operating system name (e.g., "Apple iPhone")
• browser_family: Browser type (e.g., "Safari")
• browser_major_version: Browser major version (e.g., "16.3")

Geographic Data: (Inferred from IP address, null when unavailable)

• geo_city: City (e.g., "Ottawa")
• geo_region: State/province/region (e.g., "Kansas")
• geo_country: Country (e.g., "United States")

Network Information:

• ip: Public IP address. Returns null when unavailable.

Event Type and Property Definition

Checkout Events

All checkout events will have the following properties: environment_id, checkout_id, player_id, and player_country. They will also have the following nullable fields: storefront_id, metadata, external_reference_id.

Any extra properties in addition to the standard set will be listed below.

Neon Shop Events

All Neon Shops events will have the following properties: environment_id, storefront_id, player_country. They will also have the following nullable fields: player_id, metadata.

Any extra properties in addition to the standard set will be listed below.

Property Definition

• storefront_id: Unique identifier of the Neon Shop, if one exists (e.g. Knight Fighter Sandbox Storefront → d53dcb72-b171-480e-a376-98922851fba4).
• environment_id: Unique identifier for your environment (e.g. Knight Fighter Sandbox → 91b56100-271f-4447-8a5e-2ad37259869d).
• player_id: Identifier of a player. This maps to the accountId field in our APIs.
• offer_sku: Unique SKU value associated with a particular offer within the Neon Shop.
• offer_skus: SKUs for offers associated with this event.
• metadata: Additional contextual data sent with Auth or Checkout APIs.
• checkout_id: Unique identifier assigned to each checkout process initiated by a player.
• purchase_id: Purchase identifier uniquely identifies each purchase transaction within our system.
• refund_id: Unique identifier for a processed refund transaction within our system.
• player_country: Player country in ISO 3166-1 alpha-2 (i.e., "US").
• marketing_email_consent: A boolean value that shows if a player agreed to get a marketing consent.
• payment_method: A string indicating the type of payment method used. Example values: "apple_pay", "google_pay", "paypal", "credit_or_debit_card", "toss_pay", "pix", "free", "line_pay", "sepa", "paysafecard", "grabpay", "modo", "naver_pay", "kakao_pay", "naver_or_kakao_pay", "unknown", "ovo", "oxxo", "boleto", "dana", "cash_app_pay", "klarna", "paypay", "upi", "wechat_pay", "alipay", "ideal", "bancontact", "przelewy24", "eps", "palm_pay", "opay", "providus_bank", "samsung_pay", "pix_dlocal", "blik", "neon_pay". New values may be added in the future.
• is_first_payment_method: A boolean indicating whether this is the first payment method saved for the player.
• total_saved_cards: A number representing the total count of saved cards for the player.
• total_saved_payment_methods: A number representing the total count of saved payment methods for the player.
• is_default: A boolean indicating whether this payment method is set as the default.
• is_saved_checkbox: A boolean value indicating if a player toggled the "save payment method" checkbox while on checkout.
• promo_code: A string representing the human-readable promotional code applied by the player (e.g., "20OFF", "WELCOME10").
• promo_code_id: A unique identifier assigned to each promotion or discount campaign in our system, used to reference the specific promo internally.
• error_type: A string indicating the type of error encountered while processing a payment. Example values: "insufficient_funds", "limit_exceeded", "fraudulent", "high_risk", "lost_or_stolen", "incorrect_cvc", "unauthorized", "invalid_cvc", "incorrect_number", "incorrect_zip", "invalid_exp_year", "invalid_number", "invalid_iban", "expired_card", "unexpected_country", "invalid", "invalid_exp_month","session_expired", "invalid_name", "declined", "failed". New values may be added in the future.

  Value	Trigger condition
  insufficient_funds	The card or linked account doesn't have enough available balance to cover the charge amount at the time of the attempt.
  limit_exceeded	The transaction was declined because it would exceed the card's credit limit, a per-transaction/daily spending limit, or a velocity limit (too many transactions in a short window).
  fraudulent	Neon fraud-detection systems flagged this specific transaction and declined it.
  high_risk	Declined by the card issuer for risk reasons that fall short of a confirmed fraud flag — e.g. the merchant or transaction pattern matched a risk rule, without the issuer explicitly calling
  lost_or_stolen	The card has been reported lost or stolen by the cardholder, or the issuer has flagged it for physical retention ("pickup").
  incorrect_cvc	A CVC/CVV was submitted and checked against the number on file, but it didn't match. The card number itself is fine — the security code is wrong.
  invalid_cvc	The CVC value submitted doesn't meet basic format requirements (wrong length, non-numeric, etc.) — it never reached the point of being checked against the issuer's record.
  unauthorized	The cardholder didn't complete a required authentication step — most commonly, 3D Secure (3DS) verification was required but failed or was never completed.
  incorrect_number	The card number is well-formed (right length, passes validation) but doesn't correspond to any real card on file, or was mistyped.
  incorrect_zip	The billing postal/ZIP code submitted doesn't match what the issuing bank has on file for that card, per an AVS (Address Verification System) check.
  invalid_exp_month	The expiration month field wasn't a valid month value.
  invalid_exp_year	The expiration year field wasn't a valid value.
  invalid_name	The cardholder name field submitted was invalid or didn't pass the processor's validation.
  invalid_number	The card number fails basic validation outright — wrong length, fails the checksum, or isn't a recognizable card number format at all.
  invalid_iban	Specific to SEPA payments: the IBAN provided failed structural validation before the payment could be attempted.
  expired_card	The card's expiration date, as submitted, has already passed relative to today's date.
  unexpected_country	The country associated with the card doesn't match the country expected for that checkout.
  invalid	A catch-all for invalid-transaction reasons that don't fit the categories above — e.g. a duplicate/already-processed payment, or an issue with the linked bank account itself.
  declined	A generic decline: the issuer or processor said no, without a more specific reason available.
  session_expired	The customer started the payment (e.g. scanned a QR code, was redirected to a bank/wallet page) but didn't complete it within the allowed time window.
  failed	The payment attempt failed for a reason unrelated to the payment method itself (e.g. a processor API error, malformed request, or unrecognized response) rather than a specific decline

• is_saved_payment_method: A boolean value that indicates if a payment is being done by a saved payment method.
• invalid_fields: An array with any fields that have not passed validation tests. Example values: billingAddress, phoneNumber, emailAddress, name
• action_type: A string indicating if the player closed a modal via the "try again" or "close" button. Example values: "try_again" (player clicks "Try Again" button), "close" (player closes the modal).
• external_reference_id: Additional contextual string sent with checkout APIs or backend events.
• payment_error_modal_type: A categorized error type attached to Payment Error Modal Closed event.

  Value	Trigger Condition
  payment_failed	The user's payment failed. Check the corresponding Payment Failed event for more details. Examples: The user's payment failed. Covers card declines (incorrect/invalid CVC, expired card, invalid expiry month/year, incorrect/invalid card number, incorrect ZIP, invalid IBAN, invalid name, insufficient funds), generic declines for both card and non-card payment methods (fraud, lost/stolen, high risk, other invalid/unauthorized/limit-exceeded reasons), an unsupported or mismatched card country, and payment session timeout.
  checkout_not_found	The checkout token was invalid, or the checkout is no longer available. The checkout couldn't be found, was already completed, or wasn't in an open state when the customer tried to act on it.
  checkout_expired	The checkout was open longer than its allowed window and automatically expired. A newer checkout was started for the same customer and items, invalidating this one. An item in the cart became unavailable while the checkout was open. An item's price changed while the checkout was open. A promotion applied to the checkout ended before the customer completed it. An item in the cart is no longer offered for sale — its offer end date has passed.
  checkout_state_invalid	The checkout state is invalid. Examples: An item is restricted from purchase, typically because the customer has reached the per-account purchase limit set on that item. The customer changed their checkout country, and after currency conversion the cart total fell below the minimum payment amount for the new market (e.g. $0.50 in the US, ₹1 in India). A promo code applied earlier to this checkout had expired by the time the customer tried to complete payment. Most promo-code errors are shown inline on the form input and don't fire the modal - this rare path is the exception.
  invalid_data	The user submitted invalid form data. Examples: invalid address, invalid card dates. Examples: The billing address was rejected during tax calculation as not a recognized deliverable address. The customer's billing-address country didn't match the country selected for the storefront. The Indian payment processor (Razorpay) rejected the submitted payment data as invalid. The card's expiry year failed pre-payment format validation before the charge was attempted. The phone number entered on the checkout form couldn't be parsed as a valid phone number for the customer's country.
  other_error	An unknown or uncategorized error occurred. Examples: A concurrent request held a lock on a resource the checkout needed (HTTP 409 Conflict). The customer can safely retry — the request did not execute. The customer tried to pay with NeonPay but wasn't signed in to a NeonPay account at submit time. An invitation link couldn't be matched to a pending invite — typically because it was already redeemed, revoked, or unknown. The customer account couldn't be located. The customer's billing country requires a state or region (e.g. US, Canada, India) but none was provided. Both a saved card and a fresh billing address were submitted together (only one is allowed). The merchant's inventory webhook (the endpoint Neon calls to verify item availability) returned an error, an invalid response, or rejected the customer. An error occurred that didn't match any known category. In the specific subset where the payment was attempted and the processor returned a generic non-decline failure, Payment Failed does fire alongside with error_type: failed. Most unknown modal events do not correspond to a Payment Failed event.

if you require additional information or analytics reports, please don't hesitate to contact [email protected]