ProfileService

https://madstudioroblox.github.io/ProfileService
Admin
ProfileService is a Roblox ModuleScript for loading and auto-saving player DataStore profiles with...
Tokens:26,241
Snippets:177
Trust Score:8.3
Update:3 days ago
Show doc for...
Tokens:
Raw
### Case example: Studying data mutation over time

Source: https://madstudioroblox.github.io/ProfileService/api

Example of using ProfileVersionQuery to study how data changes over time.

```APIDOC
## Case example: Studying data mutation over time

### Description
Demonstrates how to use ProfileVersionQuery to print out every snapshot of data saved over a period of time.

### Code
```lua
-- You have ProfileService working in your game. You join
--  the game with your own account and go to https://www.unixtimestamp.com
--  and save the current UNIX timestamp resembling present time.
--  You can then make the game alter your data by giving you
--  currency, items, experience, etc.

local ProfileStore = ProfileService.GetProfileStore(store_name, template)

-- UNIX timestamp you saved:
local min_date = DateTime.fromUnixTimestamp(1628952101)
local print_minutes = 5 -- Print the next 5 minutes of history

local query = ProfileStore:ProfileVersionQuery(
  "Player_2312310",
  Enum.SortDirection.Ascending,
  min_date
)

-- You can now attempt to print out every snapshot of your data saved
--  at an average periodic interval of 30 seconds (ProfileService auto-save)
--  starting from the time you took the UNIX timestamp!

local finish_update_time = min_date.UnixTimestampMillis + (print_minutes * 60000)

print("Fetching ", print_minutes, "minutes of saves:")

local entry_count = 0

while true do

  entry_count +=1
  local profile = query:NextAsync()

  if profile ~= nil then

    if profile.KeyInfo.UpdatedTime > finish_update_time then
      if entry_count == 1 then
        print("No entries found in set time period. (Start timestamp too early)")
      else
        print("Time period finished.")
      end
      break
    end

    print(
      "Entry", entry_count, "-",
      DateTime.fromUnixTimestampMillis(profile.KeyInfo.UpdatedTime):ToIsoDate()
    )

    print(profile.Data) -- Printing table for studio expressive output

  else
    if entry_count == 1 then
      print("No entries found in set time period. (Start timestamp too late)")
    else
      print("No more entries in query.")
    end
    break
  end

end
```
```

--------------------------------

### ProfileStore.Mock usage example

Source: https://madstudioroblox.github.io/ProfileService/api

Demonstrates loading both live and mock profiles and cleaning up mock profiles to prevent memory leaks.

```lua
local ProfileTemplate = {}
local GameProfileStore = ProfileService.GetProfileStore(
  "PlayerData",
  ProfileTemplate
)

local LiveProfile = GameProfileStore:LoadProfileAsync(
  "profile_key",
  "ForceLoad"
)
local MockProfile = GameProfileStore.Mock:LoadProfileAsync(
  "profile_key",
  "ForceLoad"
)
print(LiveProfile ~= MockProfile) --> true

-- When done using mock profile on live servers: (Prevent memory leak)
MockProfile:Release()
GameProfileStore.Mock:WipeProfileAsync("profile_key")
-- You don't really have to wipe mock profiles in studio testing
```

--------------------------------

### Rollback Profile Data Example

Source: https://madstudioroblox.github.io/ProfileService/api

Demonstrates how to query a previous version of a profile to perform a data rollback when a player loses items.

```lua
-- Get a ProfileStore object with the same arguments you passed to the
--  ProfileStore that loads player Profiles. It can also just be
--  the very same ProfileStore object:

local ProfileStore = ProfileService.GetProfileStore(store_name, template)

-- If you can't figure out the exact time and timezone the player lost rubies
--  in on the day of August 14th, then your best bet is to try querying
--  UTC August 13th. If the first entry still doesn't have the rubies - 
--  try a new query of UTC August 12th and etc.

local max_date = DateTime.fromUniversalTime(2021, 08, 13) -- UTC August 13th, 2021

local query = ProfileStore:ProfileVersionQuery(
  "Player_2312310", -- The same profile key that gets passed to :LoadProfileAsync()
  Enum.SortDirection.Descending,
  nil,
  max_date
)

-- Get the first result in the query:
local profile = query:NextAsync()

if profile ~= nil then

  profile:ClearGlobalUpdates()

  profile:OverwriteAsync() -- This method does the actual rolling back;
    -- Don't call this method until you're sure about setting the latest
    -- version to a copy of the previous one

  print("Rollback success!")

  print(profile.Data) -- You'll be able to surf table contents if
    -- you're runing this code in studio with access to API services
    -- enabled and have expressive output enabled; If the printed
    -- data doesn't have the rubies, you'll want to change your
    -- query parameters.

else
  print("No version to rollback to")
end
```

--------------------------------

### Handle Developer Product Purchases with ProcessReceipt

Source: https://madstudioroblox.github.io/ProfileService/tutorial/developer_products

This example defines a settings table for products, manages player profiles, and implements the PurchaseIdCheckAsync function to ensure purchases are saved before processing.

```lua
local SETTINGS = {

    ProfileTemplate = {
        Cash = 0,
    },

    Products = { -- developer_product_id = function(profile)
        [97662780] = function(profile)
            profile.Data.Cash += 100
        end,
        [97663121] = function(profile)
            profile.Data.Cash += 1000
        end,
    },

    PurchaseIdLog = 50, -- Store this amount of purchase id's in MetaTags;
        -- This value must be reasonably big enough so the player would not be able
        -- to purchase products faster than individual purchases can be confirmed.
        -- Anything beyond 30 should be good enough.

}

----- Loaded Modules -----

local ProfileService = require(game.ServerScriptService.ProfileService)

----- Private Variables -----

local Players = game:GetService("Players")
local MarketplaceService = game:GetService("MarketplaceService")

local GameProfileStore = ProfileService.GetProfileStore(
    "PlayerData",
    SETTINGS.ProfileTemplate
)

local Profiles = {} -- {player = profile, ...}

----- Private Functions -----

local function PlayerAdded(player)
    local profile = GameProfileStore:LoadProfileAsync("Player_" .. player.UserId)
    if profile ~= nil then
        profile:AddUserId(player.UserId) -- GDPR compliance
        profile:Reconcile() -- Fill in missing variables from ProfileTemplate (optional)
        profile:ListenToRelease(function()
            Profiles[player] = nil
            player:Kick() -- The profile could've been loaded on another Roblox server
        end)
        if player:IsDescendantOf(Players) == true then
            Profiles[player] = profile
        else
            profile:Release() -- Player left before the profile loaded
        end
    else
        -- The profile couldn't be loaded possibly due to other
        --   Roblox servers trying to load this profile at the same time:
        player:Kick() 
    end
end

function PurchaseIdCheckAsync(profile, purchase_id, grant_product_callback) --> Enum.ProductPurchaseDecision
    -- Yields until the purchase_id is confirmed to be saved to the profile or the profile is released

    if profile:IsActive() ~= true then

        return Enum.ProductPurchaseDecision.NotProcessedYet

    else

        local meta_data = profile.MetaData

        local local_purchase_ids = meta_data.MetaTags.ProfilePurchaseIds
        if local_purchase_ids == nil then
            local_purchase_ids = {}
            meta_data.MetaTags.ProfilePurchaseIds = local_purchase_ids
        end

        -- Granting product if not received:

        if table.find(local_purchase_ids, purchase_id) == nil then
            while #local_purchase_ids >= SETTINGS.PurchaseIdLog do
                table.remove(local_purchase_ids, 1)
            end
            table.insert(local_purchase_ids, purchase_id)
            task.spawn(grant_product_callback)
        end

        -- Waiting until the purchase is confirmed to be saved:

        local result = nil

        local function check_latest_meta_tags()
            local saved_purchase_ids = meta_data.MetaTagsLatest.ProfilePurchaseIds
            if saved_purchase_ids ~= nil and table.find(saved_purchase_ids, purchase_id) ~= nil then
                result = Enum.ProductPurchaseDecision.PurchaseGranted
            end
        end

        check_latest_meta_tags()

        local meta_tags_connection = profile.MetaTagsUpdated:Connect(function()
            check_latest_meta_tags()
            -- When MetaTagsUpdated fires after profile release:
            if profile:IsActive() == false and result == nil then
                result = Enum.ProductPurchaseDecision.NotProcessedYet
            end
        end)

        while result == nil do
            task.wait()
        end

        meta_tags_connection:Disconnect()

        return result

    end

end

local function GetPlayerProfileAsync(player) --> [Profile] / nil
    -- Yields until a Profile linked to a player is loaded or the player leaves
    local profile = Profiles[player]
    while profile == nil and player:IsDescendantOf(Players) == true do
        task.wait()
        profile = Profiles[player]
    end
    return profile
end

local function GrantProduct(player, product_id)
    -- We shouldn't yield during the product granting process!
    local profile = Profiles[player]
    local product_function = SETTINGS.Products[product_id]
    if product_function ~= nil then
        product_function(profile)
    else
        warn("ProductId " .. tostring(product_id) .. " has not been defined in Products table")
    end
end

local function ProcessReceipt(receipt_info)

    local player = Players:GetPlayerByUserId(receipt_info.PlayerId)
```

--------------------------------

### Study Data Mutation Over Time Example

Source: https://madstudioroblox.github.io/ProfileService/api

Demonstrates how to iterate through profile snapshots within a specific time range to audit data changes.

```lua
-- You have ProfileService working in your game. You join
--  the game with your own account and go to https://www.unixtimestamp.com
--  and save the current UNIX timestamp resembling present time.
--  You can then make the game alter your data by giving you
--  currency, items, experience, etc.

local ProfileStore = ProfileService.GetProfileStore(store_name, template)

-- UNIX timestamp you saved:
local min_date = DateTime.fromUnixTimestamp(1628952101)
local print_minutes = 5 -- Print the next 5 minutes of history

local query = ProfileStore:ProfileVersionQuery(
  "Player_2312310",
  Enum.SortDirection.Ascending,
  min_date
)

-- You can now attempt to print out every snapshot of your data saved
--  at an average periodic interval of 30 seconds (ProfileService auto-save)
--  starting from the time you took the UNIX timestamp!

local finish_update_time = min_date.UnixTimestampMillis + (print_minutes * 60000)

print("Fetching ", print_minutes, "minutes of saves:")

local entry_count = 0

while true do

  entry_count +=1
  local profile = query:NextAsync()

  if profile ~= nil then

    if profile.KeyInfo.UpdatedTime > finish_update_time then
      if entry_count == 1 then
        print("No entries found in set time period. (Start timestamp too early)")
      else
        print("Time period finished.")
      end
      break
    end

    print(
      "Entry", entry_count, "-",
      DateTime.fromUnixTimestampMillis(profile.KeyInfo.UpdatedTime):ToIsoDate()
    )

    print(profile.Data) -- Printing table for studio expressive output

  else
    if entry_count == 1 then
      print("No entries found in set time period. (Start timestamp too late)")
    else
      print("No more entries in query.")
    end
    break
  end

end
```

--------------------------------

### Case example: "I lost all of my rubies on August 14th!"

Source: https://madstudioroblox.github.io/ProfileService/api

Example of using ProfileVersionQuery to roll back a profile to a previous version.

```APIDOC
## Case example: "I lost all of my rubies on August 14th!"

### Description
Demonstrates how to use ProfileVersionQuery to find and roll back to a previous version of a profile.

### Code
```lua
-- Get a ProfileStore object with the same arguments you passed to the
--  ProfileStore that loads player Profiles. It can also just be
--  the very same ProfileStore object:

local ProfileStore = ProfileService.GetProfileStore(store_name, template)

-- If you can't figure out the exact time and timezone the player lost rubies
--  in on the day of August 14th, then your best bet is to try querying
--  UTC August 13th. If the first entry still doesn't have the rubies - 
--  try a new query of UTC August 12th and etc.

local max_date = DateTime.fromUniversalTime(2021, 08, 13) -- UTC August 13th, 2021

local query = ProfileStore:ProfileVersionQuery(
  "Player_2312310", -- The same profile key that gets passed to :LoadProfileAsync()
  Enum.SortDirection.Descending,
  nil,
  max_date
)

-- Get the first result in the query:
local profile = query:NextAsync()

if profile ~= nil then

  profile:ClearGlobalUpdates()

  profile:OverwriteAsync() -- This method does the actual rolling back;
    -- Don't call this method until you're sure about setting the latest
    -- version to a copy of the previous one

  print("Rollback success!")

  print(profile.Data) -- You'll be able to surf table contents if
    -- you're runing this code in studio with access to API services
    -- enabled and have expressive output enabled; If the printed
    -- data doesn't have the rubies, you'll want to change your
    -- query parameters.

else
  print("No version to rollback to")
end
```
```

--------------------------------

### Conditional ProfileStore.Mock setup

Source: https://madstudioroblox.github.io/ProfileService/api

Configures the game to use mock profiles automatically when running in Roblox Studio.

```lua
local RunService = game:GetService("RunService")
local GameProfileStore = ProfileService.GetProfileStore("PlayerData", ProfileTemplate)
if RunService:IsStudio() == true then
  GameProfileStore = GameProfileStore.Mock
end
```

--------------------------------

### Listening to New Active Updates

Source: https://madstudioroblox.github.io/ProfileService/api

Example of listening for new active updates and locking them immediately.

```lua
profile.GlobalUpdates:ListenToNewActiveUpdate(function(update_id, update_data)
  profile.GlobalUpdates:LockActiveUpdate(update_id)
end)
```

--------------------------------

### ProfileStore:GlobalUpdateProfileAsync() usage

Source: https://madstudioroblox.github.io/ProfileService/api

Example of using GlobalUpdateProfileAsync to add an active update to a profile.

```lua
ProfileStore:GlobalUpdateProfileAsync(
  "Player_2312310",
  function(global_updates)
    global_updates:AddActiveUpdate({
      Type = "AdminGift",
      Item = "Coins",
      Amount = 1000,
    })
  end
)
```

--------------------------------

### ProfileStore:LoadProfileAsync() with handler

Source: https://madstudioroblox.github.io/ProfileService/api

Example of using a function as the not_released_handler to handle session locks by returning a specific action string.

```lua
local profile = ProfileStore:LoadProfileAsync(
  "Player_2312310",
  function(place_id, game_job_id)
    -- place_id and game_job_id identify the Roblox server that has
    --   this profile currently locked. In rare cases, if the server
    --   crashes, the profile will stay locked until ForceLoaded by
    --   a new session.
    return "Repeat" or "Cancel" or "ForceLoad" or "Steal"
  end
)
```

--------------------------------

### Profile.KeyInfoUpdated

Source: https://madstudioroblox.github.io/ProfileService/api

A signal that gets triggered every time Profile.KeyInfo is updated with a new DataStoreKeyInfo instance reference after every auto-save or profile release.

```APIDOC
## Profile.KeyInfoUpdated

### Description
ScriptSignal that gets triggered every time Profile.KeyInfo is updated with a new DataStoreKeyInfo instance reference after every auto-save or profile release.

### Signal Parameters
- **key_info** (DataStoreKeyInfo) - The new DataStoreKeyInfo instance.
```

--------------------------------

### Initialize MarketplaceService and existing players

Source: https://madstudioroblox.github.io/ProfileService/tutorial/developer_products

Initializes the receipt processing and ensures existing players are handled upon script startup.

```lua
for _, player in ipairs(Players:GetPlayers()) do
    task.spawn(PlayerAdded, player)
end

MarketplaceService.ProcessReceipt = ProcessReceipt
```

--------------------------------

### Profile.RobloxMetaData

Source: https://madstudioroblox.github.io/ProfileService/api

Table that gets saved as Metadata of a DataStore key belonging to the profile. Equivalent to using DataStoreSetOptions:SetMetaData().

```APIDOC
## Profile.RobloxMetaData

### Description
Table that gets saved as Metadata (Official documentation) of a DataStore key belonging to the profile. The way this table is saved is equivalent to using DataStoreSetOptions:SetMetaData(Profile.RobloxMetaData) and passing the DataStoreSetOptions object to a :SetAsync() call, except changes will truly get saved on the next auto-update cycle or when the profile is released.

### Type
Table (non-strict reference)

### Remarks
- Be cautious of very harsh limits for maximum Roblox Metadata size - total table content size cannot exceed 300 characters.
- After the profile is released, further changes to this value will not be saved.

### Example
```lua
local profile -- A profile object you loaded

-- Mimicking the Roblox hub example:
profile.RobloxMetaData = {["ExperienceElement"] = "Fire"}

-- You can read from it and write to it at will:
print(profile.RobloxMetaData.ExperienceElement)
profile.RobloxMetaData.ExperienceElement = nil
profile.RobloxMetaData.UserCategory = "Casual"

-- I think setting it to a whole table at profile load would
--   be more safe considering the size limit for meta data
--   is pretty tight:
profile.RobloxMetaData = {
  UserCategory = "Casual",
  FavoriteColor = {1, 0, 0},
}
```
```

--------------------------------

### Profile.KeyInfo Reference

Source: https://madstudioroblox.github.io/ProfileService/api

The DataStoreKeyInfo instance associated with the profile.

```lua
Profile.KeyInfo [DataStoreKeyInfo]
```

--------------------------------

### ProcessReceipt implementation for developer products

Source: https://madstudioroblox.github.io/ProfileService/tutorial/developer_products

Handles product purchase decisions by verifying the player profile and purchase ID before granting the product.

```lua
    if player == nil then
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end

    local profile = GetPlayerProfileAsync(player)

    if profile ~= nil then

        return PurchaseIdCheckAsync(
            profile,
            receipt_info.PurchaseId,
            function()
                GrantProduct(player, receipt_info.ProductId)
            end
        )

    else
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end

end
```

--------------------------------

### Basic Profile Loader Implementation

Source: https://madstudioroblox.github.io/ProfileService/tutorial/basic_usage

A complete implementation for loading player profiles, handling GDPR compliance, reconciling data, and managing profile release.

```lua
-- ProfileTemplate table is what empty profiles will default to.
-- Updating the template will not include missing template values
--   in existing player profiles!
local ProfileTemplate = {
    Cash = 0,
    Items = {},
    LogInTimes = 0,
}

----- Loaded Modules -----

local ProfileService = require(game.ServerScriptService.ProfileService)

----- Private Variables -----

local Players = game:GetService("Players")

local ProfileStore = ProfileService.GetProfileStore(
    "PlayerData",
    ProfileTemplate
)

local Profiles = {} -- [player] = profile

----- Private Functions -----

local function GiveCash(profile, amount)
    -- If "Cash" was not defined in the ProfileTemplate at game launch,
    --   you will have to perform the following:
    if profile.Data.Cash == nil then
        profile.Data.Cash = 0
    end
    -- Increment the "Cash" value:
    profile.Data.Cash = profile.Data.Cash + amount
end

local function DoSomethingWithALoadedProfile(player, profile)
    profile.Data.LogInTimes = profile.Data.LogInTimes + 1
    print(player.Name .. " has logged in " .. tostring(profile.Data.LogInTimes)
        .. " time" .. ((profile.Data.LogInTimes > 1) and "s" or ""))
    GiveCash(profile, 100)
    print(player.Name .. " owns " .. tostring(profile.Data.Cash) .. " now!")
end

local function PlayerAdded(player)
    local profile = ProfileStore:LoadProfileAsync("Player_" .. player.UserId)
    if profile ~= nil then
        profile:AddUserId(player.UserId) -- GDPR compliance
        profile:Reconcile() -- Fill in missing variables from ProfileTemplate (optional)
        profile:ListenToRelease(function()
            Profiles[player] = nil
            -- The profile could've been loaded on another Roblox server:
            player:Kick()
        end)
        if player:IsDescendantOf(Players) == true then
            Profiles[player] = profile
            -- A profile has been successfully loaded:
            DoSomethingWithALoadedProfile(player, profile)
        else
            -- Player left before the profile loaded:
            profile:Release()
        end
    else
        -- The profile couldn't be loaded possibly due to other
        --   Roblox servers trying to load this profile at the same time:
        player:Kick() 
    end
end

----- Initialize -----

-- In case Players have joined the server earlier than this script ran:
for _, player in ipairs(Players:GetPlayers()) do
    task.spawn(PlayerAdded, player)
end

----- Connections -----

Players.PlayerAdded:Connect(PlayerAdded)

Players.PlayerRemoving:Connect(function(player)
    local profile = Profiles[player]
    if profile ~= nil then
        profile:Release()
    end
end)
```

--------------------------------

### Profile:ListenToRelease() Method

Source: https://madstudioroblox.github.io/ProfileService/api

Subscribes a listener to be called when the profile is released remotely or locally. It is recommended to kick the player when this occurs.

```lua
Profile:ListenToRelease(listener) --> [ScriptConnection] (place_id / nil, game_job_id / nil)
-- listener   [function] (place_id / nil, game_job_id / nil)
```

--------------------------------

### ProfileService.IssueSignal

Source: https://madstudioroblox.github.io/ProfileService/api

A ScriptSignal that fires with error details for DataStore error logging. Connect to this signal to handle errors, for example by sending analytics events.

```APIDOC
## ProfileService.IssueSignal

### Description
Analytics endpoint for DataStore error logging. Fires with error_message, profile_store_name, and profile_key.

### Signal
ProfileService.IssueSignal [ScriptSignal](error_message [string], profile_store_name [string], profile_key [string])

### Example
```lua
ProfileService.IssueSignal:Connect(function(error_message, profile_store_name, profile_key)
  pcall(function()
    AnalyticsService:FireEvent(
      "ProfileServiceIssue",
      error_message,
      profile_store_name,
      profile_key
    )
  end)
end)
```
```

--------------------------------

### Profile:Identify() Method

Source: https://madstudioroblox.github.io/ProfileService/api

Returns a string containing the DataStore name, scope, and key for debugging purposes.

```lua
Profile:Identify() --> [string]
-- Example return: "[Store:"GameData";Scope:"Live";Key:"Player_2312310"]"
```

--------------------------------

### Profile:ListenToHopReady() Method

Source: https://madstudioroblox.github.io/ProfileService/api

Executes a listener after the profile release is fully processed, useful for handling universe teleports. It waits until the session lock is removed.

```lua
Profile:ListenToHopReady(listener) --> [ScriptConnection] ()
-- listener   [function] ()
```

```lua
local TeleportService = game:GetService("TeleportService")
local profile, player, place_id

profile:Release()
profile:ListenToHopReady(function()
  TeleportService:TeleportAsync(place_id, {player})
end)
```

--------------------------------

### Manage PlayerAdded and PlayerRemoving connections

Source: https://madstudioroblox.github.io/ProfileService/tutorial/developer_products

Sets up event listeners for player join and leave events to manage profile lifecycle.

```lua
Players.PlayerAdded:Connect(PlayerAdded)

Players.PlayerRemoving:Connect(function(player)
    local profile = Profiles[player]
    if profile ~= nil then
        profile:Release()
    end
end)
```

--------------------------------

### Profile.KeyInfo

Source: https://madstudioroblox.github.io/ProfileService/api

The DataStoreKeyInfo instance related to this profile.

```APIDOC
## Profile.KeyInfo

### Description
The DataStoreKeyInfo (Official documentation) instance related to this profile.

### Type
DataStoreKeyInfo
```

--------------------------------

### ProfileService.GetProfileStore method

Source: https://madstudioroblox.github.io/ProfileService/api

Initializes a ProfileStore object, similar to Roblox's GetDataStore. Accepts a store index (string or table) and a template table for default profile data.

```lua
ProfileService.GetProfileStore(
    profile_store_index,
    profile_template
) --> [ProfileStore]
-- profile_store_index   [string] -- DataStore name
-- OR
-- profile_store_index   [table]: -- Allows the developer to define more GlobalDataStore variables
--  {
--    Name = "StoreName", -- [string] -- DataStore name
--    -- Optional arguments:
--    Scope = "StoreScope", -- [string] -- DataStore scope
--  }
-- profile_template     [table] -- Profile.Data will default to
--   given table (deep-copy) when no data was saved previously
```

--------------------------------

### Profile:ListenToRelease()

Source: https://madstudioroblox.github.io/ProfileService/api

Subscribes a listener function that will be called when the profile is released remotely (being 'ForceLoad'ed on a remote server) or locally (Profile:Release()). In common practice, the profile will rarely be released before the player leaves the game, so it's recommended to simply :Kick() the Player when this happens.

```APIDOC
## Profile:ListenToRelease()

### Description
Listener functions subscribed to `Profile:ListenToRelease()` will be called when the profile is released remotely (Being `"ForceLoad"`'ed on a remote server) or locally (`Profile:Release()`). In common practice, the profile will rarely be released before the player leaves the game so it's recommended to simply :Kick() the Player when this happens.

### Method
Profile:ListenToRelease(listener)

### Parameters
- **listener** (function) - Required - A function that will be called with (place_id / nil, game_job_id / nil) when the profile is released.

### Returns
[ScriptConnection] (place_id / nil, game_job_id / nil)

### Warning
After `Profile:ListenToRelease()` is triggered, it is too late to change `Profile.Data` for the final time. As long as the profile is active (`Profile:IsActive()` == `true`), you should store all profile related data immediately after it becomes available. An item trading operation between two profiles must happen without any yielding after it is confirmed that both profiles are active.
```

--------------------------------

### Profile:ListenToHopReady()

Source: https://madstudioroblox.github.io/ProfileService/api

Executes a listener after the releasing UpdateAsync call finishes, typically around a second but may take up to 7 seconds when a profile is released next to an auto-update interval. Useful for teleport scenarios to avoid delays when loading profiles after a universe teleport.

```APIDOC
## Profile:ListenToHopReady()

### Description
In many cases ProfileService will be fast enough when loading and releasing profiles as the player teleports between places belonging to the same universe / game. However, if you're experiencing noticable delays when loading profiles after a universe teleport, you should try implementing `:ListenToHopReady()`.

A listener passed to `:ListenToHopReady()` will be executed after the releasing UpdateAsync call finishes. `:ListenToHopReady()` will usually call the listener in around a second, but may ocassionally take up to 7 seconds when a profile is released next to an auto-update interval (regular usage scenario - rapid loading / releasing of the same profile key may yield different results).

### Method
Profile:ListenToHopReady(listener)

### Parameters
- **listener** (function) - Required - A function that will be called with no arguments when the profile is ready for teleport.

### Returns
[ScriptConnection] ()

### Example Use
```lua
local TeleportService = game:GetService("TeleportService")
local profile, player, place_id

profile:Release()
profile:ListenToHopReady(function()
  TeleportService:TeleportAsync(place_id, {player})
end)
```

### Notes
In short, `Profile:ListenToRelease()` and `Profile:ListenToHopReady()` will both execute the listener function after release, but `Profile:ListenToHopReady()` will additionally wait until the session lock is removed from the `Profile`.
```

--------------------------------

### Verify profile release with print

Source: https://madstudioroblox.github.io/ProfileService/troubleshooting

Add a print statement to your PlayerRemoving event to confirm that profiles are being released successfully.

```lua
Players.PlayerRemoving:Connect(function(player)
    local profile = Profiles[player]
    if profile ~= nil then
        profile:Release()
        print(player.Name .. "'s profile has been released!")
    end
end)
```

--------------------------------

### Mistake #3: Yielding before Release

Source: https://madstudioroblox.github.io/ProfileService/troubleshooting

Avoid using wait() or any yielding functions before releasing a profile, as this delays the release and risks race conditions.

```lua
Players.PlayerRemoving:Connect(function(player)
    local profile = Profiles[player]
    if profile ~= nil then
        wait(1) -- Or any function with "Wait", "Async" or "Yield" in its name
        profile:Release()
    end
end)
```

--------------------------------

### ProfileStore:ProfileVersionQuery()

Source: https://madstudioroblox.github.io/ProfileService/api

Creates a profile version query using DataStore:ListVersionsAsync(). Results are retrieved through ProfileVersionQuery:Next().

```APIDOC
## ProfileStore:ProfileVersionQuery()

### Description
Creates a profile version query using DataStore:ListVersionsAsync(). Results are retrieved through ProfileVersionQuery:Next().

### Method
ProfileStore:ProfileVersionQuery()

### Parameters
- **profile_key** (string) - Required - The profile key.
- **sort_direction** (nil or Enum.SortDirection) - Optional - Defaults to "Ascending".
- **min_date** (nil or DateTime or number) - Optional - Epoch time millis.
- **max_date** (nil or DateTime or number) - Optional - Epoch time millis.

### Returns
- **ProfileVersionQuery** - A query object that can be used to retrieve versions via Next().

### Example
```lua
local ProfileStore = ProfileService.GetProfileStore(store_name, template)

local query = ProfileStore:ProfileVersionQuery(
  "Player_2312310",
  Enum.SortDirection.Descending,
  nil,
  max_date
)

local profile = query:NextAsync()
```
```

--------------------------------

### Profile:Identify()

Source: https://madstudioroblox.github.io/ProfileService/api

Returns a string containing DataStore name, scope and key; Used for debugging.

```APIDOC
## Profile:Identify()

### Description
Returns a string containing DataStore name, scope and key; Used for debugging.

### Method
Profile:Identify()

### Parameters
None

### Returns
[string] - Example return: "[Store:"GameData";Scope:"Live";Key:"Player_2312310"]"
```

--------------------------------

### ProfileService.IssueSignal usage

Source: https://madstudioroblox.github.io/ProfileService/api

Connect to this signal to log DataStore errors to an analytics service.

```lua
ProfileService.IssueSignal   [ScriptSignal](error_message [string], profile_store_name [string], profile_key [string])
```

```lua
ProfileService.IssueSignal:Connect(function(error_message, profile_store_name, profile_key)
  pcall(function()
    AnalyticsService:FireEvent(
      "ProfileServiceIssue",
      error_message,
      profile_store_name,
      profile_key
    )
  end)
end)
```

--------------------------------

### Mistake #2: Erroring code before Release

Source: https://madstudioroblox.github.io/ProfileService/troubleshooting

Ensure that no functions called before profile:Release() can error, as an error will prevent the release from executing.

```lua
Players.PlayerRemoving:Connect(function(player)
    local profile = Profiles[player]
    if profile ~= nil then
        SaveData(profile) -- Are you sure this function doesn't error?
        profile:Release()
    end
end)
```

--------------------------------

### ProfileStore.Mock

Source: https://madstudioroblox.github.io/ProfileService/api

A reflection of ProfileStore methods that operate on a separate, detached fake DataStore. Useful for testing without affecting live data, and can be used in parallel with the live ProfileStore.

```APIDOC
## ProfileStore.Mock

### Description
A reflection of methods available in the ProfileStore object, but operations are performed on a separate, detached fake DataStore that is forgotten when the game session ends. Profiles loaded from ProfileStore and ProfileStore.Mock with the same key are completely isolated from each other.

### Usage
```lua
local ProfileTemplate = {}
local GameProfileStore = ProfileService.GetProfileStore("PlayerData", ProfileTemplate)

local LiveProfile = GameProfileStore:LoadProfileAsync("profile_key", "ForceLoad")
local MockProfile = GameProfileStore.Mock:LoadProfileAsync("profile_key", "ForceLoad")
print(LiveProfile ~= MockProfile) --> true

-- When done using mock profile on live servers: (Prevent memory leak)
MockProfile:Release()
GameProfileStore.Mock:WipeProfileAsync("profile_key")
```

### Studio Testing Example
```lua
local RunService = game:GetService("RunService")
local GameProfileStore = ProfileService.GetProfileStore("PlayerData", ProfileTemplate)
if RunService:IsStudio() == true then
  GameProfileStore = GameProfileStore.Mock
end
```

### Notes
- Even when Roblox API services are disabled, ProfileStore and ProfileStore.Mock store profiles in separate stores.
- Think of ProfileStore and ProfileStore.Mock as two different ProfileStore objects unrelated to each other.
- It is possible to use both live and mock profiles on live servers.
```

--------------------------------

### ProfileStore:ProfileVersionQuery() Signature

Source: https://madstudioroblox.github.io/ProfileService/api

The method signature for ProfileVersionQuery, defining the required parameters for querying profile versions.

```lua
ProfileStore:ProfileVersionQuery(profile_key, sort_direction, min_date, max_date) --> [ProfileVersionQuery]
-- profile_key      [string]
-- sort_direction   nil or [Enum.SortDirection] -- Defaults to "Ascending"
-- min_date         nil or [DateTime] or [number] (epoch time millis)
-- max_date         nil or [DateTime] or [number] (epoch time millis)
```

--------------------------------

### ProfileService.GetProfileStore()

Source: https://madstudioroblox.github.io/ProfileService/api

Creates and returns a ProfileStore object for loading and viewing profiles and sending global updates. Equivalent to :GetDataStore() in Roblox DataStoreService API.

```APIDOC
## ProfileService.GetProfileStore()

### Description
Creates a ProfileStore object that exposes methods for loading / viewing profiles and sending global updates. Equivalent of :GetDataStore() in Roblox DataStoreService API.

### Method
ProfileService.GetProfileStore(profile_store_index, profile_template) --> [ProfileStore]

### Parameters
- **profile_store_index** (string or table) - Required - DataStore name as a string, or a table with Name and optional Scope fields.
- **profile_template** (table) - Required - Profile.Data will default to this table (deep-copy) when no data was saved previously.

### Example
```lua
-- Using a string index
local store = ProfileService.GetProfileStore("StoreName", {})

-- Using a table index
local store = ProfileService.GetProfileStore({
    Name = "StoreName",
    Scope = "StoreScope"
}, {})
```
```

--------------------------------

### ProfileStore:GlobalUpdateProfileAsync(profile_key, update_handler)

Source: https://madstudioroblox.github.io/ProfileService/api

Creates and manages Active global updates for a specified profile. Can be called on any Roblox server and updates should reach the recipient in less than 30 seconds.

```APIDOC
## ProfileStore:GlobalUpdateProfileAsync(profile_key, update_handler)

### Description
Creates and manages Active global updates for a specified profile. Can be called on any Roblox server and updates should reach the recipient in less than 30 seconds.

### Method
GlobalUpdateProfileAsync

### Parameters
#### profile_key
- **type**: string
- **Required**: Yes
- **Description**: DataStore key for the profile.

#### update_handler
- **type**: function
- **Required**: Yes
- **Description**: Called with a GlobalUpdates object. Use this to add active updates.

### Return Value
- **type**: GlobalUpdates or nil
- **Description**: Returns a GlobalUpdates object, or nil if the operation fails.

### Usage Notes
- Works for profiles that haven't been created yet.
- Yielding inside the update_handler will throw an error.
- Avoid rapid use of this method to prevent dead session locks and lost Profile.Data.

### Example
```lua
ProfileStore:GlobalUpdateProfileAsync(
  "Player_2312310",
  function(global_updates)
    global_updates:AddActiveUpdate({
      Type = "AdminGift",
      Item = "Coins",
      Amount = 1000,
    })
  end
)
```
```

--------------------------------

### Profile:Reconcile() Method

Source: https://madstudioroblox.github.io/ProfileService/api

Fills in missing variables in Profile.Data from the profile_template. Use this when updating your template after a game release.

```lua
Profile:Reconcile() --> nil
```

--------------------------------

### ProfileStore:LoadProfileAsync(profile_key, not_released_handler)

Source: https://madstudioroblox.github.io/ProfileService/api

Loads a profile for a given DataStore key. The not_released_handler can be nil, a string, or a function to handle session-locked profiles.

```APIDOC
## ProfileStore:LoadProfileAsync(profile_key, not_released_handler)

### Description
Loads a profile for a given DataStore key. The not_released_handler can be nil, a string, or a function to handle session-locked profiles.

### Method
LoadProfileAsync

### Parameters
#### profile_key
- **type**: string
- **Required**: Yes
- **Description**: DataStore key for the profile.

#### not_released_handler
- **type**: nil, string, or function
- **Required**: No
- **Description**: Determines behavior when the profile is session-locked. Defaults to "ForceLoad".
  - If string: "ForceLoad" or "Steal".
  - If function: Called with (place_id, game_job_id) and must return "Repeat", "Cancel", "ForceLoad", or "Steal".

### Return Value
- **type**: Profile or nil
- **Description**: Returns a Profile object, or nil if loading fails or is cancelled.

### Usage Notes
- Pass nil for not_released_handler for basic usage.
- The function handler is called when the profile is session-locked by a remote Roblox server.
- The handler must return one of: "Repeat", "Cancel", "ForceLoad", or "Steal".
- LoadProfileAsync can return nil when another remote server attempts to load the same profile at the same time.
- Do not load a profile of the same key again before it is released.

### Example
```lua
local profile = ProfileStore:LoadProfileAsync(
  "Player_2312310",
  function(place_id, game_job_id)
    -- place_id and game_job_id identify the Roblox server that has
    --   this profile currently locked. In rare cases, if the server
    --   crashes, the profile will stay locked until ForceLoaded by
    --   a new session.
    return "Repeat" or "Cancel" or "ForceLoad" or "Steal"
  end
)
```
```

--------------------------------

### Profile:AddUserId() Method

Source: https://madstudioroblox.github.io/ProfileService/api

Associates a UserId with the profile for GDPR compliance.

```lua
Profile:AddUserId(user_id)
-- user_id   [number]
```

--------------------------------

### Profile.RobloxMetaData Usage

Source: https://madstudioroblox.github.io/ProfileService/api

Table saved as DataStore key metadata with a strict 300-character limit.

```lua
Profile.RobloxMetaData [table]
-- Non-strict reference - developer can set this value to a new table reference
```

```lua
local profile -- A profile object you loaded

-- Mimicking the Roblox hub example:
profile.RobloxMetaData = {["ExperienceElement"] = "Fire"}

-- You can read from it and write to it at will:
print(profile.RobloxMetaData.ExperienceElement)
profile.RobloxMetaData.ExperienceElement = nil
profile.RobloxMetaData.UserCategory = "Casual"

-- I think setting it to a whole table at profile load would
--   be more safe considering the size limit for meta data
--   is pretty tight:
profile.RobloxMetaData = {
  UserCategory = "Casual",
  FavoriteColor = {1, 0, 0},
}
```

--------------------------------

### ProfileStore:LoadProfileAsync() signature

Source: https://madstudioroblox.github.io/ProfileService/api

The signature for the LoadProfileAsync method, which loads a profile by key and accepts an optional not_released_handler.

```lua
ProfileStore:LoadProfileAsync(
  profile_key,
  not_released_handler
) --> [Profile] or nil
-- profile_key            [string] -- DataStore key
-- not_released_handler   nil or []: -- Defaults to "ForceLoad"
--      [string] "ForceLoad" -- Force loads profile on first call
--      OR
--      [string] "Steal" -- Steals the profile ignoring it's session lock
--      OR
--      [function] (place_id, game_job_id) --> [string] "Repeat", "Cancel", "ForceLoad" or "Steal"
--          place_id      [number] or nil
--          game_job_id   [string] or nil
```

--------------------------------

### Profile.MetaData Structure

Source: https://madstudioroblox.github.io/ProfileService/api

Contains read-only information about the profile and writable MetaTags.

```lua
Profile.MetaData [table] (Read-only) -- Data about the profile itself

Profile.MetaData.ProfileCreateTime [number] (Read-only)
-- os.time() timestamp of profile creation

Profile.MetaData.SessionLoadCount [number] (Read-only)
-- Amount of times the profile was loaded

Profile.MetaData.ActiveSession [table] or nil (Read-only)
-- {place_id, game_job_id} or nil
-- Set to a session link if a Roblox server is currently the
--   owner of this profile; nil if released

Profile.MetaData.MetaTags [table] (Writable)
-- {["tag_name"] = tag_value, ...}
-- Saved and auto-saved just like Profile.Data

Profile.MetaData.MetaTagsLatest [table] (Read-only)
-- the most recent version of MetaData.MetaTags which has
--   been saved to the DataStore during the last auto-save
--   or Profile:Save() call
```

--------------------------------

### ProfileService.CriticalStateSignal property

Source: https://madstudioroblox.github.io/ProfileService/api

Analytics endpoint for monitoring severe DataStore errors that may impact game functionality.

```lua
ProfileService.CriticalStateSignal   [ScriptSignal] (is_critical_state [bool])
```

--------------------------------

### GlobalUpdates:ListenToNewActiveUpdate() Signature

Source: https://madstudioroblox.github.io/ProfileService/api

Registers a listener for new active updates.

```lua
GlobalUpdates:ListenToNewActiveUpdate(listener) --> [ScriptConnection]
-- listener   [function](update_id, update_data)
```

--------------------------------

### Profile:Save()

Source: https://madstudioroblox.github.io/ProfileService/api

Triggers a quick save to progress GlobalUpdates state and speed up propagation of MetaTags changes to MetaTagsLatest. Does not yield and should not be used for saving Profile.Data or MetaTags.

```APIDOC
## Profile:Save()

### Description
Triggers a quick save to progress GlobalUpdates state and speed up propagation of MetaTags changes to MetaTagsLatest. Does not yield and should not be used for saving Profile.Data or MetaTags.

### Method
Profile:Save

### Parameters
None

### Usage Example
```lua
profile:Save()
```

### Notes
- Should not be called for saving Profile.Data or Profile.MetaData.MetaTags - this is done automatically.
- Calling this method when the Profile is released will throw an error. Check Profile:IsActive() before using.
```

--------------------------------

### Profile:Reconcile()

Source: https://madstudioroblox.github.io/ProfileService/api

Fills in missing variables inside Profile.Data from the profile_template table provided when calling ProfileService.GetProfileStore(). It is often necessary to use this method when applying changes to the profile_template over the course of a game's development after release.

```APIDOC
## Profile:Reconcile()

### Description
Fills in missing variables inside `Profile.Data` from the `profile_template` table that was provided when calling `ProfileService.GetProfileStore()`. It's often necessary to use `:Reconcile()` if you're applying changes to your `profile_template` over the course of your game's development after release.

### Method
Profile:Reconcile()

### Parameters
None

### Returns
nil

### Notes
The right time to call this method can be seen in the basic usage example.

The following function is used in the reconciliation process:
```lua
local function ReconcileTable(target, template)
    for k, v in pairs(template) do
        if type(k) == "string" then -- Only string keys will be reconciled
            if target[k] == nil then
                if type(v) == "table" then
                    target[k] = DeepCopyTable(v)
                else
                    target[k] = v
                end
            elseif type(target[k]) == "table" and type(v) == "table" then
                ReconcileTable(target[k], v)
            end
        end
    end
end
```
```

--------------------------------

### Profile:GetMetaTag Method

Source: https://madstudioroblox.github.io/ProfileService/api

Retrieves a specific meta tag value.

```lua
Profile:GetMetaTag(tag_name) --> value
-- tag_name   [string]
```

--------------------------------

### ProfileStore:ViewProfileAsync(profile_key, version)

Source: https://madstudioroblox.github.io/ProfileService/api

Loads the latest profile version (or a specified version) from the DataStore without claiming a session lock. Returns nil if the version does not exist. The returned Profile does not auto-save and releasing has no effect. Data can be modified and saved via Profile:OverwriteAsync().

```APIDOC
## ProfileStore:ViewProfileAsync(profile_key, version)

### Description
Attempts to load the latest profile version (or a specified version via the `version` argument) from the DataStore without claiming a session lock. Returns `nil` if such version does not exist. Returned `Profile` will not auto-save and releasing won't do anything. Data in the returned `Profile` can be changed to create a payload which can be saved via Profile:OverwriteAsync().

### Method
ViewProfileAsync

### Parameters
- **profile_key** (string) - Required - DataStore key
- **version** (nil or string) - Optional - DataStore key version

### Return Value
- [Profile] or nil

### Notes
- Passing `version` argument in mock mode (or offline mode) will throw an error - Mock versioning is not supported.
- `:ViewProfileAsync()` is the preferred way of viewing player data without editing it.
```
Tokens:
Raw