GS2-Friend Transaction Actions

Specification of verify/consume/acquire transaction actions

Combining actions, and concurrency

The background common to every service is collected in Combining Transaction Actions. Read that first; the rest of this section is what GS2-Friend adds to it.

GS2-Friend provides one transaction action. A profile is identified by the combination of namespace and user, and there is one per user. It is rewritten as a whole on every update.

Operation	Repeated in one transaction	Across a nested transaction	Boundary that separates targets
Updating a profile `UpdateProfileByUserId`	Folded into one if the values are identical; an error (400) if they differ	Passes if identical; fails if they differ	namespace, user

An update replaces the whole profile, so two updates cannot be composed into one. Two updates with the same content are folded into one, and updates with differing values are rejected when the transaction is issued — the same treatment as the absolute-value actions of other services, the ones whose names begin with Set. Decide the profile you want and specify it once.

Friend requests, follows, and blocks are not transaction actions, so nothing else in GS2-Friend competes for the profile.

Take care with nested transactions

Where the same profile is updated both from the inside and from the outside, the outcome is the same as within one transaction: identical values pass, differing values fail. Only the timing differs — within one transaction the error is returned when the transaction is issued, across a nested transaction it surfaces when the transaction is committed.

If you want to avoid these restrictions

Updating a profile is an acquire action, so turning acquireActionUseJobQueue on clears a collision between the inside and the outside. Turning enableAtomicCommit off also stops the inside-outside collision, but then the later update wins.

Concurrency and retries

A profile is rewritten as a whole with a revision check, so when several requests update the same profile at the same time, the one confirmed later returns a conflict (409). Nothing is wrong with the request, so retrying will succeed, and the profile is re-read on the retry.

A profile belongs to one user, so this only happens when the same user’s profile is updated from several places at once.

Acquire Action

Gs2Friend:UpdateProfileByUserId

Update profile by User ID

Updates the specified user’s profile with three distinct visibility levels (server-side operation):

publicProfile: visible to all users
followerProfile: visible only to followers
friendProfile: visible only to friends

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
publicProfile	string		~ 1024 chars	Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information.
followerProfile	string		~ 1024 chars	Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages.
friendProfile	string		~ 1024 chars	Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages.
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Friend:UpdateProfileByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "publicProfile": "[string]Public profile",
        "followerProfile": "[string]Profile for followers",
        "friendProfile": "[string]Profile for friends",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Friend:UpdateProfileByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  publicProfile: "[string]Public profile"
  followerProfile: "[string]Profile for followers"
  friendProfile: "[string]Profile for friends"
  timeOffsetToken: "[string]Time offset token"

transaction.service("friend").acquire.update_profile_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    publicProfile="[string]Public profile",
    followerProfile="[string]Profile for followers",
    friendProfile="[string]Profile for friends",
    timeOffsetToken="[string]Time offset token",
})