# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: AnalyticsService
type: class
memory_category: Instances
summary: |
  Collection of methods that allows developers to track how users interact with
  their experiences.
description: |
  `AnalyticsService` is a collection of methods that allows developers to track
  how users interact with their experiences, specifically player progression,
  in-experience economy, funnels, and custom events.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
  - NotReplicated
deprecation_message: ''
properties:
  - name: AnalyticsService.ApiKey
    summary: |
      PlayFab API key. Must be set in order to use
      `Class.AnalyticsService:FireEvent()|FireEvent`.
    description: |
      The **ApiKey** property contains the game's PlayFab API key. It must be
      set and valid in order to use
      `Class.AnalyticsService:FireEvent()|FireEvent`. It can be set by pasting
      and editing the following line of code into the Command bar:

      ```lua
      game:GetService("AnalyticsService").ApiKey = "API_KEY"
      ```
    code_samples: []
    type: string
    tags:
      - Deprecated
    deprecation_message: ''
    security:
      read: LocalUserSecurity
      write: LocalUserSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
methods:
  - name: AnalyticsService:FireCustomEvent
    summary: |
      Fires a custom event with a custom event name and data.
    description: |
      This function triggers a custom event with a custom event name data.

      #### Limits of events

      Each game server is allowed a certain number of standard events API calls
      based on the number of players present (more players means more events
      will be needed). The events that exceed the limit will be dropped and log
      an error to the developer console. - Per minute limit: 120 + numPlayers \*
      20, all events shared this limit. - Cooldown: refresh every 10 seconds

      #### Limits of parameters

      Limit the size of parameters. The event that exceeds the limit will be
      dropped and log an error to the developer console.

      <table>
          <thead>
              <tr>
                  <th>Parameters</th>
                  <th>Maximum Number of Characters</th>
              </tr>
          </thead>
          <tbody>
              <tr>
                  <td>customData Variant</td>
                  <td>500 after serialized</td>
              </tr>
              <tr>
                  <td>other string types</td>
                  <td>50</td>
              </tr>
          </tbody>
      </table>

      See also:

      - `Class.AnalyticsService:FirePlayerProgressionEvent()`, triggers an event
        used to track player progression through the game
      - `Class.AnalyticsService:FireInGameEconomyEvent()`, triggers an event
        used to track player actions pertaining to the in-game economy
      - `Class.AnalyticsService:FireLogEvent()`, triggers an event used to track
        errors and warnings experienced by players
    code_samples:
      - analytics-event---custom
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The player who triggered the custom event. `nil` if not player
          related.
      - name: eventCategory
        type: string
        default:
        summary: |
          User defined category. This should be the name of the event.
      - name: customData
        type: Variant
        default:
        summary: |
          Optional. User defined data, could be a string, a number or a table.
    returns:
      - type: ()
        summary: ''
    tags:
      - Deprecated
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:FireEvent
    summary: |
      Report a custom event to PlayFab.
    description: |
      **FireEvent** reports a custom event to PlayFab. The event is reported
      using a **category** and **value**, where the category is a string and the
      value can be a string or table. In order to use PlayFab, you must have a
      valid `Class.AnalyticsService.ApiKey|ApiKey` set.

      #### Possible Errors

      - **"AnalyticsService can only be executed by game server."** – Tracking
        can only be done on the server through a `Class.Script` or
        `Class.ModuleScript` required by a script. See
        `Class.RunService:IsServer()`.
      - **"The ApiKey is invalid."** – The
        `Class.AnalyticsService.ApiKey|ApiKey` has been set, but it's invalid.
        Check that it is set to the correct value.
      - **"AnalyticsService can only accept valid UTF-8 characters."** – Thrown
        when the value can't be serialized as UTF-8 characters. This can happen
        if you pass a value which has unicode characters, like emojis.
      - **"AnalyticsService failed in parse event value. Error: ..."** – Thrown
        when there is an issue when serializing the provided value into a
        string.
      - **"AnalyticsService: , " and \r\n are not allowed in category."** – The
        comma `,`, the double quote `"`, and newline characters `\r\n` cannot be
        used in the **category** parameter.
      - **"AnalyticsService: The event value you fired is too long."** – Thrown
        if the **value** parameter was too long after serialization. The length
        limit is 1 KiB, or 1024 bytes.
    code_samples: []
    parameters:
      - name: category
        type: string
        default:
        summary: |
          'The category of event to report. Cannot contain the following
          characters: comma `,`, double quote `"` or newline characters `\r\n`'.
      - name: value
        type: Variant
        default:
        summary: |
          A value to be serialized and reported. Serialized length must not
          exceed 1 KiB, or 1024 bytes.
    returns:
      - type: ()
        summary: ''
    tags:
      - Deprecated
    deprecation_message: |
      This function has been deprecated in favor of more descriptive methods,
      including:

      - `Class.AnalyticsService:FireCustomEvent()`
      - `Class.AnalyticsService:FireInGameEconomyEvent()`
      - `Class.AnalyticsService:FireLogEvent()`
      - `Class.AnalyticsService:FirePlayerProgressionEvent()`
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:FireInGameEconomyEvent
    summary: |
      Fire an event used to track player actions pertaining to the in-game
      economy.
    description: |
      This function triggers an event used to track player actions pertaining to
      the in-game economy.

      For example, it should be called to track when players acquire or spend
      virtual items within the economy like currency.

      #### Limits of events

      Each game server is allowed a certain number of standard events API calls
      based on the number of players present (more players means more events
      will be needed). The events that exceed the limit will be dropped and log
      an error to the developer console. - Per minute limit: 120 + numPlayers \*
      20, all events shared this limit. - Cooldown: refresh every 10 seconds

      #### Limits of parameters

      Limit the size of parameters. The event that exceeds the limit will be
      dropped and log an error to the developer console.

      <table>
          <thead>
              <tr>
                  <th>Parameters</th>
                  <th>Maximum Number of Characters</th>
              </tr>
          </thead>
          <tbody>
              <tr>
                  <td>customData Variant</td>
                  <td>500 after serialized</td>
              </tr>
              <tr>
                  <td>other string types</td>
                  <td>50</td>
              </tr>
          </tbody>
      </table>

      See also:

      - `Class.AnalyticsService:FirePlayerProgressionEvent()`, triggers an event
        used to track player progression through the game
      - `Class.AnalyticsService:FireLogEvent()`, triggers an event used to track
        errors and warnings experienced by players
      - `Class.AnalyticsService:FireCustomEvent()`, triggers an event used to
        emit a custom event
    code_samples:
      - analytics-event---economy
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The player who triggered the economy event.
      - name: itemName
        type: string
        default:
        summary: |
          The name of the item.
      - name: economyAction
        type: AnalyticsEconomyAction
        default:
        summary: |
          Indicates the acquisition or spending of an in game resource.
      - name: itemCategory
        type: string
        default:
        summary: |
          A user defined category for items such as "Vehicle," "Weapon.".
      - name: amount
        type: int
        default:
        summary: |
          The amount of the currency.
      - name: currency
        type: string
        default:
        summary: |
          The currency used. Examples: 'gold', 'gems', 'life.'.
      - name: location
        type: Variant
        default:
        summary: |
          The event location. A dictionary that each key-value represents an
          entry of location data. The key-value is a string-string pair. With
          this you can query which are the most popular "stores" then maybe you
          want to increase/lower the price for the stores.

          See the example below:

          ```lua
          local location = {
              ["placeDesc"] = "Dungeon1",
              ["levelDesc"] = "level2",
              ["mapDesc"] = "LeftChamberMap",
              ["storeName"] = "DarkSmith",
              ["userDefinedKey"] = "0005"
          }
          ```
      - name: customData
        type: Variant
        default:
        summary: |
          Optional. User defined data, could be a string, a number or a table.
    returns:
      - type: ()
        summary: |
          No return.
    tags:
      - Deprecated
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:FireLogEvent
    summary: |
      Fire a log event used to track errors and warnings experienced by players.
    description: |
      This function triggers an event used to track errors and warnings
      experienced by players.

      For example, it could be called to indicate when a function call fails -
      such as a datastore save or `Class.TeleportService:Teleport()`. See the
      example below.

      #### Limits of events

      Each game server is allowed a certain number of standard events API calls
      based on the number of players present (more players means more events
      will be needed). The events that exceed the limit will be dropped and log
      an error to the developer console. - Per minute limit: 120 + numPlayers \*
      20, all events shared this limit. - Cooldown: refresh every 10 seconds

      #### Limits of parameters

      Limit the size of parameters. The event that exceeds the limit will be
      dropped and log an error to the developer console.

      <table>
          <thead>
              <tr>
                  <th>Parameters</th>
                  <th>Maximum Number of Characters</th>
              </tr>
          </thead>
          <tbody>
              <tr>
                  <td>FireLogEvent stackTrace</td>
                  <td>1000</td>
              </tr>
              <tr>
                  <td>FireLogEvent message</td>
                  <td>500</td>
              </tr>
              <tr>
                  <td>customData Variant</td>
                  <td>500 after serialized</td>
              </tr>
              <tr>
                  <td>other string types</td>
                  <td>50</td>
              </tr>
          </tbody>
      </table>

      See also:

      - `Class.AnalyticsService:FireInGameEconomyEvent()`, triggers an event
        used to track player actions pertaining to the in-game economy
      - `Class.AnalyticsService:FirePlayerProgressionEvent()`, triggers an event
        used to track player progression through the game
      - `Class.AnalyticsService:FireCustomEvent()`, triggers an event used to
        emit a custom event
    code_samples:
      - analytics-event---log
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The player who triggered the error event, `nil` if not player related.
      - name: logLevel
        type: AnalyticsLogLevel
        default:
        summary: |
          The specified log level (e.g. Debug, Error).
      - name: message
        type: string
        default:
        summary: |
          User defined message.
      - name: debugInfo
        type: Variant
        default:
        summary: |
          Optional. A dictionary which contains predefined keys including
          "errorCode" and "stackTrace". Both keys values are strings. stackTrace
          is a traceback of the current function call stack.

          ```lua
          local debugInfo = {
                      errorCode = '123',
                      stackTrace = debug.traceback()
                }
          ```
      - name: customData
        type: Variant
        default:
        summary: |
          Optional. User defined data, could be a string, a number or a table.
    returns:
      - type: ()
        summary: |
          No return.
    tags:
      - Deprecated
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:FirePlayerProgressionEvent
    summary: |
      Fire an event used to track player progression through the game.
    description: |
      This function triggers an event used to track player progression through
      the game.

      For example, it should be called when a player starts an in-game tutorial
      and again that player finishes the tutorial. Another example (see below)
      includes tracking when a player gains experience, collects objects, and
      levels up.

      #### Limits of events

      Each game server is allowed a certain number of standard events API calls
      based on the number of players present (more players means more events
      will be needed). The events that exceed the limit will be dropped and log
      an error to the developer console. - Per minute limit: 120 + numPlayers \*
      20, all events shared this limit. - Cooldown: refresh every 10 seconds

      #### Limits of parameters

      Limit the size of parameters. The event that exceeds the limit will be
      dropped and log an error to the developer console.

      <table>
          <thead>
              <tr>
                  <th>Parameters</th>
                  <th>Maximum Number of Characters</th>
              </tr>
          </thead>
          <tbody>
              <tr>
                  <td>FirePlayerProgressionEvent location</td>
                  <td>5 pairs of Key and Value, each Key and Value are 50</td>
              </tr>
              <tr>
                  <td>FirePlayerProgressionEvent statistics</td>
                  <td>5 pairs of Key and Value, each Key and Value are 50</td>
              </tr>
              <tr>
                  <td>customData Variant</td>
                  <td>500 after serialized</td>
              </tr>
              <tr>
                  <td>other string types</td>
                  <td>50</td>
              </tr>
          </tbody>
      </table>

      See also:

      - `Class.AnalyticsService:FireInGameEconomyEvent()`, triggers an event
        used to track player actions pertaining to the in-game economy
      - `Class.AnalyticsService:FireLogEvent()`, triggers an event used to track
        errors and warnings experienced by players
      - `Class.AnalyticsService:FireCustomEvent()`, triggers an event used to
        emit a custom event
    code_samples:
      - analytics-event---progression
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The player who triggered the event.
      - name: category
        type: string
        default:
        summary: |
          A user defined category for progression.
      - name: progressionStatus
        type: AnalyticsProgressionStatus
        default:
        summary: |
          Indicates the status of the progression.
      - name: location
        type: Variant
        default:
        summary: |
          The event location. A dictionary that each key-value represents an
          entry of location data. The key-value is a string-string pair. With
          this developers can query where is the most frequent location for a
          specific progression event category. For example, the category could
          be "LevelUp".

          ```lua
          local location = {
              ["placeDesc"] = "Dungeon1",
              ["levelDesc"] = "level2",
              ["mapDesc"] = "LeftChamberMap",
              ["ProgresionType"] = "LevelUp",
              ["userDefinedKey5"] = "0005"
          }
          ```
      - name: statistics
        type: Variant
        default:
        summary: |
          Optional. A dictionary that each key-value represents an entry of
          statistics data that allows developers to track any specific data that
          they want to collect as players progress through their game. Key-Value
          is a string-number pair.

          ```lua
          local statistics = {
              ["numberOfKills"] = 111,
              ["numberOfExp"] = 222,
              ["userDefinedKey3"] = number,
              ["userDefinedKey4"] = number,
              ["userDefinedKey5"] = number
          }
          ```
      - name: customData
        type: Variant
        default:
        summary: |
          Optional. User defined data, could be a string, a number or a table.
    returns:
      - type: ()
        summary: |
          No return.
    tags:
      - Deprecated
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogCustomEvent
    summary: |
      Logs an event used to track custom metrics of a user in experience.
    description: |
      Logs an event used to track custom metrics of a user in experience. For
      additional information, see
      [custom events](../../../production/analytics/custom-events.md).
    code_samples:
      - Log-Custom-Event
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The user who triggered the event.
      - name: eventName
        type: string
        default:
        summary: |
          The name of the custom event.
      - name: value
        type: double
        default: 1
        summary: |
          The value of the event that will be used in aggregation.
      - name: customFields
        type: Dictionary
        default: nil
        summary: |
          Optional dictionary of custom fields that will provide breakdowns in
          Roblox-provided charts. Only specific keys, provided by
          `Enum.AnalyticsCustomFieldKeys`, will be used for these breakdowns.
          Limited to 8,000 unique combinations of values across the three custom
          fields per experience.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogEconomyEvent
    summary: |
      Logs an event used to track player actions related in experience.
    description: |
      Logs an event used to track player actions related in experience.
    code_samples:
      - AnalyticsService-LogEconomyEvent-IAP
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The user who triggered the event.
      - name: flowType
        type: AnalyticsEconomyFlowType
        default:
        summary: |
          Should specify the direction that currency is flowing using
          `Enum.AnalyticsEconomyFlowType`.
      - name: currencyType
        type: string
        default:
        summary: |
          The name of the currency being added or removed, for example `"gold"`,
          `"gems"`, or `"energy"`. Limited to 5 unique currency types per
          experience.
      - name: amount
        type: float
        default:
        summary: |
          The amount of currency being added or removed. This value should
          always be positive.
      - name: endingBalance
        type: float
        default:
        summary: |
          The user's balance after the currency has been added or removed. This
          value should always be greater than or equal to `0`.
      - name: transactionType
        type: string
        default:
        summary: |
          The type of transaction that occurred. While you're free to use any
          transaction type, it's recommended to use the provided types from
          `Enum.AnalyticsEconomyTransactionType` such as `"IAP"` or
          `"ContextualPurchase"` to enable future insights from Roblox tools and
          charts.

          Because this field type is a string, you'll need to pass the `Name`
          value of the enum. For example
          `Enum.AnalyticsEconomyTransactionType|Enum.AnalyticsEconomyTransactionType.IAP.Name`.

          Limited to 20 unique types per experience.
      - name: itemSku
        type: string
        default:
        summary: |
          Optional SKU of the item or bundle being purchased. This is a unique
          identifier for the item being purchased. Limited to 100 unique SKUs
          per experience.
      - name: customFields
        type: Dictionary
        default: nil
        summary: |
          Optional dictionary of custom fields that will provide breakdowns in
          Roblox-provided charts. Only specific keys, provided by
          `Enum.AnalyticsCustomFieldKeys`, will be used for these breakdowns.
          Limited to 8,000 unique combinations of values across the three custom
          fields per experience.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogFunnelStepEvent
    summary: |
      Logs an event used to track user actions stepping through a pre-planned
      funnel.
    description: |
      Logs an event used to track user actions stepping through a pre-planned
      funnel. Funnel breakdowns will only consider the user and event values
      from the first step in a funnel session.
    code_samples:
      - AnalyticsService-LogFunnelStepEvent-Shop
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The user who triggered the event.
      - name: funnelName
        type: string
        default:
        summary: |
          The name of the funnel. This should be the same for all steps in the
          funnel. Limited to 10 unique funnels per experience.
      - name: funnelSessionId
        type: string
        default:
        summary: |
          Optional unique identifier for the funnel session. This should be the
          same for all steps in the funnel.

          Note that this field is only necessary for **recurring** funnels, for
          example a purchase flow funnel or an item upgrade funnel. If you don't
          have a natural funnel session identifier, it's recommended to use
          `Class.HttpService:GenerateGUID()`.
      - name: step
        type: int
        default: 1
        summary: |
          The step number in the funnel. This should be unique for each step in
          the funnel. All funnels start at step 1. Limited to steps 1-100.

          Repeated steps by the same user in the same funnel session, or when
          `funnelSessionId` is `nil` will be ignored.

          Note that if any steps are skipped, the intermediate steps will be
          considered completed.
      - name: stepName
        type: string
        default:
        summary: |
          Optional name of the step in the funnel. This field is only used for
          display purposes in Roblox-provided charts.
      - name: customFields
        type: Dictionary
        default: nil
        summary: |
          Optional dictionary of custom fields that will provide breakdowns in
          Roblox-provided charts. Only specific keys, provided by
          `Enum.AnalyticsCustomFieldKeys`, will be used for these breakdowns.
          Limited to 8,000 unique combinations of values across the three custom
          fields per experience.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogOnboardingFunnelStepEvent
    summary: |
      Logs an event used to track user actions stepping through an onboarding
      funnel.
    description: |
      Logs an event used to track user actions stepping through an onboarding
      funnel. Funnel breakdowns will only consider the user and event values
      from the first step in a funnel session.
    code_samples:
      - AnalyticsService-LogOnboardingFunnelStepEvent-TwoSteps
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The user who triggered the event.
      - name: step
        type: int
        default:
        summary: |
          The step number in the funnel. This should be unique for each step in
          the funnel. All funnels start at step 1. Limited to steps 1-100.

          Note that if any steps are skipped, the intermediate steps will be
          considered completed.
      - name: stepName
        type: string
        default:
        summary: |
          Optional name of the step in the funnel. This field is only used for
          display purposes in Roblox-provided charts.
      - name: customFields
        type: Dictionary
        default: nil
        summary: |
          Optional dictionary of custom fields that will provide breakdowns in
          Roblox-provided charts. Only specific keys, provided by
          `Enum.AnalyticsCustomFieldKeys`, will be used for these breakdowns.
          Limited to 8,000 unique combinations of values across the three custom
          fields per experience.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogProgressionCompleteEvent
    summary: |
      Logs an event for when a user has completed a level attempt.
    description: |
      Logs an event for when a user has completed a level attempt. This event
      does not currently display in any Roblox-provided charts.
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The player who triggered the event.
      - name: progressionPathName
        type: string
        default:
        summary: ''
      - name: level
        type: int
        default:
        summary: ''
      - name: levelName
        type: string
        default:
        summary: ''
      - name: customFields
        type: Dictionary
        default: nil
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogProgressionEvent
    summary: |
      Logs an event for when a user has started, completed, or failed a level
      attempt.
    description: |
      Logs an event for when a user has started, completed, or failed a level
      attempt. This event does not currently display in any Roblox-provided
      charts.
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The player who triggered the event.
      - name: progressionPathName
        type: string
        default:
        summary: ''
      - name: status
        type: AnalyticsProgressionType
        default:
        summary: ''
      - name: level
        type: int
        default:
        summary: ''
      - name: levelName
        type: string
        default:
        summary: ''
      - name: customFields
        type: Dictionary
        default: nil
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogProgressionFailEvent
    summary: |
      Logs an event for when a user has failed a level attempt.
    description: |
      Logs an event for when a user has failed a level attempt. This event does
      not currently display in any Roblox-provided charts.
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The user who triggered the event.
      - name: progressionPathName
        type: string
        default:
        summary: ''
      - name: level
        type: int
        default:
        summary: ''
      - name: levelName
        type: string
        default:
        summary: ''
      - name: customFields
        type: Dictionary
        default: nil
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: AnalyticsService:LogProgressionStartEvent
    summary: |
      Logs an event for when a user has started a level attempt.
    description: |
      Logs an event for when a user has started a level attempt. This event does
      not currently display in any Roblox-provided charts.
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          The player who triggered the event.
      - name: progressionPathName
        type: string
        default:
        summary: ''
      - name: level
        type: int
        default:
        summary: ''
      - name: levelName
        type: string
        default:
        summary: ''
      - name: customFields
        type: Dictionary
        default: nil
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
events: []
callbacks: []