Social System

Repository: git clone https://gitlab.com/AcceleratXR/Core/social_services.git

A service that provides social features to users including a social profile, online presence, friends list, blocked players list and player-to-player messaging.

Player-to-Player Messaging

The social services system supports the sending and receiving of player-to-player messages. Each message has a senderUid of the user sending the message, a receiverUid of the user that the message is destined for as well as subject, body and attachments.

Inbox

Each user has their own inbox of messages that they have been sent by other users accessible via the /{userUid}/messages/inbox endpoint. Messages are considered permanent and will not be deleted or removed unless the application specifically removes them. To improve the user interface usability of your application a hasRead property is provided for each message that indicates whether or not a message has been read. It is the responsibility of the application to mark a message has having been read by either performing an update or calling GET on the /messages/{messageUid}/read endpoint.

Sent Messages

Each user can access the list of all sent messages using the /{userUid}/messages/sent endpoint. Like received messages the system will not automatically delete sent messages. It is the responsibility of the application to delete sent messages. Note however that messages are not duplicated therefore the sent message and the received message are the same. Therefore, if the receiving user deletes their message it will also be removed from the sender’s sent box.

Attachments

Messages can have an optional list of attachments appended to them. The actual storage is handled as a key-value pair mapping where the key is the name of the attachment. Values are always stored as strings. To encode binary data in the attachment it is recommended to use Base64 encoding for the value.

Example

attachments: {
    file: "lkfj098fu3oajf9083ufj2oij9p0a8ffujloiua9o8ubvf9p2ulijhqrlvfb98l26yqo9283yrh2r2=",
    invite: "{ appID: \"fa72de2c-77a4-494a-b6c3-b47f51d63a9a\", type: \"game\", sessionUid: \"49b58da1-61a1-4c8e-9f45-61b8007cb765\" }"
}

Privacy & Security Considerations

Only messages that have been specifically sent to or from a given user may be accessible through the REST API. The system will automatically filter out any messages belonging to another user. Similarly, any attempt to perform an action on a message that does not belong to a given user will be denied.

User Profile

The user Profile is for storing social profile data about a user. The Profile object contains information such as the user’s current online presence, an alternate name or alias by which the user wants to identify to others as, as well as an arbitrary set of data that can contain any application-specific metadata.

Alias

Often times a user wishes to be identifiable by another name from their real name. The alias is a way for a user to provide this alternate name that can be displayed to others. The alias is not gauranteed to be unique within the system.

Avatar

The avatar property stores a UUID, URI or other identifier that the application uses to render or display an custom avatar for the user.

Presence

Online presence is application-specific data that allows other users to know what their friends are actively doing. The presence property takes an arbitrary data object that can contain any useful information that the application needs to identify and display the current state of the user. The value of this property does not have an expiration time associated with it. Therefore, it is the responsibility of the client application to update this property when the state changes, including during a logout event as the user logs offline.

Data

The data property allows an application to store any arbitrary social profile information that the user and/or application may care about. The value is stored as a key-value pair object whose keys are the names of the data properties desired.

For example let’s assume an application that stores links to various third-party social networking profiles for a given user. This may look like the following.

data: {
    facebook: "https://www.facebook.com/acceleratxr",
    linkedin: "https://www.linkedin.com/company/acceleratxr/",
    twitter: "https://twitter.com/acceleratxr",
},

User Links

A user link is a relationship of one user to another. A user can have any number of links to any number of other users. Each link describes a relationship from one user to another. This makes it possible to implement the following social network concepts.

• User Follow

• Friends

• Blocked Users

• Recently Met Users

The structure of the UserLink appears as follows:

{
    uid: "",
    dateCreated: "",
    dateModified: "",
    version: 0,
    userUid: "",
    otherUid: "",
    type: "FOLLOW"
}

Encountering Users (ENCOUNTER)

When players encounter one another while interacting in the product it is possible to create an ENCOUNTER user link. This link is intended to track all players that a user may have recently met and desire to see again in the future.

Following Users (FOLLOW)

User links with the FOLLOW type describes relationships where a user is interested in being following the activity of another user. This relationship is one-way in that the source user (userUid) wants to follow the activity other user (otherUid). This makes it possible to create loosely coupled relationships between users which can be beneficial when needing to create and maintain a set of one-way relationships for users such as subscribing to a user’s feed.

Friending Users (FRIEND)

A user link with the FRIEND type is the two-way relationship whereby two users indepedently have chosen to follow the other. As this is a two-way relationship, requiring both users to participate, it is not possible to simply create a user link with the FRIEND type. Instead, any time two users create a FOLLOW link to each other the system willl automatically upgrade their relationship to a FRIEND type. Should either side choose to delete their respective side of the relationship then the opposing link will be downgraded down to a FOLLOW link.

For applications implementing a friends list system it is recommended that each user creates a FOLLOW link to another and then sends a friend invite message to encourage the other user to create the needed opposite link to complete the FRIEND relationship. This can be accomplished via the following steps.

Given user A wants to add user B as a friend…

1. User A creates a UserLink to user B with type FOLLOW.

2. User A sends message to user B containing an invite attachment to add them as a friend.

{
    senderUid: <UserA_UUID>,
    receiverUid: <UserB_UUID>,
    subject: "UserA wants to be your friend!",
    body: "User A wants to be your friend.",
    attachments: {
        invite: "{ type: \"userlink\", userUid: <UserA_UUID> }"
    }
}

1. User B receives message containing friend invite sent by User A.

2. User B accepts friend invite. Creates a UserLink to user A with type FOLLOW

3. System automatically upgrades both connections to FRIEND

Blocking Users (BLOCK)

Not everyone is going to want to be friends. In the event that a user wishes not to interact with another user they can create a UserLink with the BLOCK type. This relationship is always a one-way relationship however it is special in that the system will not allow a user to create an opposing FOLLOW link if an existing BLOCK exists. Similarly, if there exists a FOLLOW relationship between the two users then that link will be removed once a BLOCK link is created. This is true even in the event that a FRIEND relationship exists. In the event that a user attempts to follow a user that has blocked them an error is returned by the service. It is the responsibilty of the application to decide whether or not this error should be displayed to the user.

REST API

AuthToken

The following is the list of all members included in the data schema.

Member	Description	Type	Format/Schema	Default Value	Identifier	Unique	Required
token		string		""	false	false	true

Examples

Members

token

Type: string

Default Value: ""

Required: true

Count

The following is the list of all members included in the data schema.

Member	Description	Type	Format/Schema	Default Value	Identifier	Unique	Required
count		number		0	false	false	true

Examples

Members

count

Type: number

Default Value: 0

Required: true

Profile

An Profile is an object containing a user’s specific social metadata and information. Each profile can have an alias name by which to identify the user other than their real name. A data property is provided to allow for an arbitrary storage of any metadata desired by the application. A presence property is also provided for storing the applications-specific current online state of the user.

The following is the list of all members included in the data schema.

Member	Description	Type	Format/Schema	Default Value	Identifier	Unique	Required
alias	The non-unique alternate name of the user.	string		""	false	false	true
avatar	The URL, asset uid or other global identifier that references the user’s avatar.	string		""	false	false	true
data	An arbitrary map of key-value pairs containing the metadata of the profile.	any		undefined	false	false	true
presence	A string containing encoded data about a user’s current online state.	string		""	false	false	true

Examples

Members

alias

Type: string

Default Value: ""

Required: true

The non-unique alternate name of the user.

avatar

Type: string

Default Value: ""

Required: true

The URL, asset uid or other global identifier that references the user’s avatar.

data

Type: any

Default Value: undefined

Required: true

An arbitrary map of key-value pairs containing the metadata of the profile.

presence

Type: string

Default Value: ""

Required: true

A string containing encoded data about a user’s current online state.

Message

The Message is a persistent message or notification that is sent from one user to another.

The following is the list of all members included in the data schema.

Member	Description	Type	Format/Schema	Default Value	Identifier	Unique	Required
receiverUid	The unique identifier of the user that is to receive the message.	string		""	false	false	true
senderUid	The unique identifier of the user that sent the message.	string		""	false	false	true
subject	The summary of the message contents.	string		""	false	false	true
body	The message contents.	string		""	false	false	true
attachments	A map of key-value pairs representing a list of attachments that have been appended to the message. The key of each pair is the name of the attachment and the value must be an encoded string. The string can represent any data including binary data using base64 encoding.	any		undefined	false	false	true

Examples

Members

receiverUid

Type: string

Default Value: ""

Required: true

The unique identifier of the user that is to receive the message.

senderUid

Type: string

Default Value: ""

Required: true

The unique identifier of the user that sent the message.

subject

Type: string

Default Value: ""

Required: true

The summary of the message contents.

body

Type: string

Default Value: ""

Required: true

The message contents.

attachments

Type: any

Default Value: undefined

Required: true

A map of key-value pairs representing a list of attachments that have been appended to the message. The key of each pair is the name of the attachment and the value must be an encoded string. The string can represent any data including binary data using base64 encoding.

UserLink

The UserLink is a representation of a relationship from one user to another. Relatiopships have four potential states; block, encounter, follow, or friend. The block state describes a relationship to a user that the individual wishes not to encounter. The encounter state describes a person whom the user recently interacted with. The follow state describes a person whom the user wishes to encounter again in the future. The friend state describes a person that both users wish to encounter in the future. A friend link is automatically made when each user creates a follow link to each other.

The following is the list of all members included in the data schema.

Member	Description	Type	Format/Schema	Default Value	Identifier	Unique	Required
userUid	The unique identifier of the user that owns the link.	string		""	false	false	true
otherUid	The unique identifier of the other user the the link is for.	string		""	false	false	true
status	The current state of the link.	string		follow	false	false	true

Examples

Members

userUid

Type: string

Default Value: ""

Required: true

The unique identifier of the user that owns the link.

otherUid

Type: string

Default Value: ""

Required: true

The unique identifier of the other user the the link is for.

status

Type: string

Default Value: follow

Required: true

The current state of the link.

Profile Route

Routes

FindAll

GET <base_url>/profiles

Authentication: Required

Returns all profiles from the system that the user has access to Parameters ^^^^^^^^^^

Query

Name	Description	Type	Default Value
limit	The maximimum number of results to return. Cannot exceed 1000.	number	100
skip	The number of items to skip in the results (pagination).	number	0
sort	An object containing the name of the member to sort by and the order in which to sort.	object	{ member: "<ASC|DESC>" }

Create

POST <base_url>/profiles

Authentication: Required

Create a new profile. Parameters ^^^^^^^^^^

Count

GET <base_url>/profiles/count

Authentication: Required

Returns the count of profiles Parameters ^^^^^^^^^^

FindById

GET <base_url>/profiles/:id

Authentication: Required

Returns a single profile from the system that the user has access to Parameters ^^^^^^^^^^ * Name id

Update

PUT <base_url>/profiles/:id

Authentication: Required

Updates a single profile Parameters ^^^^^^^^^^ * Name id

Delete

DELETE <base_url>/profiles/:id

Authentication: Required

Deletes the profile Parameters ^^^^^^^^^^ * Name id

FindByUserUid

GET <base_url>/profiles/:userUid/profile

Authentication: Required

Returns the profile from the system for the given user. Parameters ^^^^^^^^^^ * Name userUid

UpdateByUserUid

PUT <base_url>/profiles/:userUid/profile

Authentication: Required

Creates or updates the profile for the given user. Parameters ^^^^^^^^^^ * Name userUid

DeleteByUserUid

DELETE <base_url>/profiles/:userUid/profile

Authentication: Required

Deletes the profile for the given user. Parameters ^^^^^^^^^^ * Name userUid

GetUserPresence

GET <base_url>/profiles/:userUid/profile/presence

Authentication: Required

Returns the profile presence data for the given user. Parameters ^^^^^^^^^^ * Name userUid

SetUserPresence

PUT <base_url>/profiles/:userUid/profile/presence

Authentication: Required

Sets the profile presence data for the given user. Parameters ^^^^^^^^^^ * Name userUid

Message Route

Routes

FindAll

GET <base_url>/messages

Authentication: Required

Returns all messages from the system that the user has access to Parameters ^^^^^^^^^^

Query

Name	Description	Type	Default Value
limit	The maximimum number of results to return. Cannot exceed 1000.	number	100
skip	The number of items to skip in the results (pagination).	number	0
sort	An object containing the name of the member to sort by and the order in which to sort.	object	{ member: "<ASC|DESC>" }

Create

POST <base_url>/messages

Authentication: Required

Create a new message. Parameters ^^^^^^^^^^

Count

GET <base_url>/messages/count

Authentication: Required

Returns the count of messages Parameters ^^^^^^^^^^

FindById

GET <base_url>/messages/:id

Authentication: Required

Returns a single message from the system that the user has access to Parameters ^^^^^^^^^^ * Name id

Delete

DELETE <base_url>/messages/:id

Authentication: Required

Deletes the message Parameters ^^^^^^^^^^ * Name id

MarkRead

GET <base_url>/messages/:id/read

Authentication: Required

Marks the message with the given id as having been read by the user. Parameters ^^^^^^^^^^ * Name id

FindInboxByUserUid

GET <base_url>/messages/:userUid/inbox

Authentication: Required

Returns all of the messages from the system that have been sent to the given user. Parameters ^^^^^^^^^^ * Name userUid

DeleteInboxByUserUid

DELETE <base_url>/messages/:userUid/inbox

Authentication: Required

Deletes all messages sent to the given user. Parameters ^^^^^^^^^^ * Name userUid

FindSentByUserUid

GET <base_url>/messages/:userUid/sent

Authentication: Required

Returns all of the messages from the system that have been sent by the given user. Parameters ^^^^^^^^^^ * Name userUid

DeleteSentByUserUid

DELETE <base_url>/messages/:userUid/sent

Authentication: Required

Deletes all messages sent by the given user. Parameters ^^^^^^^^^^ * Name userUid

FindByIdAndUserUid

GET <base_url>/messages/:userUid/{id}

Authentication: Required

Returns the messages from the system with the given id that was sent to the given user. Parameters ^^^^^^^^^^ * Name userUid * Name id

DeleteByIdAndUserUid

DELETE <base_url>/messages/:userUid/{id}

Authentication: Required

Deletes the message with the given id that sent to the given user. Parameters ^^^^^^^^^^ * Name userUid * Name id

MarkReadByIdAndUserId

GET <base_url>/messages/:userUid/{id}/read

Authentication: Required

Marks the message with the given id as having been read by the user. Parameters ^^^^^^^^^^ * Name userUid * Name id

UserLink Route

Routes

FindAll

GET <base_url>/userlinks

Authentication: Required

Returns all links from the system that the user has access to Parameters ^^^^^^^^^^

Query

Name	Description	Type	Default Value
limit	The maximimum number of results to return. Cannot exceed 1000.	number	100
skip	The number of items to skip in the results (pagination).	number	0
sort	An object containing the name of the member to sort by and the order in which to sort.	object	{ member: "<ASC|DESC>" }

Create

POST <base_url>/userlinks

Authentication: Required

Create a new link. Parameters ^^^^^^^^^^

Count

GET <base_url>/userlinks/count

Authentication: Required

Returns the count of links Parameters ^^^^^^^^^^

FindById

GET <base_url>/userlinks/:id

Authentication: Required

Returns a single link from the system that the user has access to Parameters ^^^^^^^^^^ * Name id

Update

PUT <base_url>/userlinks/:id

Authentication: Required

Updates a single link Parameters ^^^^^^^^^^ * Name id

Delete

DELETE <base_url>/userlinks/:id

Authentication: Required

Deletes the link Parameters ^^^^^^^^^^ * Name id

FindByUserUid

GET <base_url>/userlinks/:userUid/links

Authentication: Required

Returns all links associated with a given user. Parameters ^^^^^^^^^^ * Name userUid

CreateByUserUid

POST <base_url>/userlinks/:userUid/links

Authentication: Required

Creates a new link for a given user. Parameters ^^^^^^^^^^ * Name userUid

SetByUserUid

PUT <base_url>/userlinks/:userUid/links

Authentication: Required

Sets the list of all links for a given user. Parameters ^^^^^^^^^^ * Name userUid

DeleteByUserUid

DELETE <base_url>/userlinks/:userUid/links

Authentication: Required

Deletes all links for a given user. Parameters ^^^^^^^^^^ * Name userUid

FindByIdAndUserUid

GET <base_url>/userlinks/:userUid/links/{id}

Authentication: Required

Returns a single link for the given user and id. Parameters ^^^^^^^^^^ * Name userUid * Name id

UpdateByIdAndUserUid

PUT <base_url>/userlinks/:userUid/links/{id}

Authentication: Required

Updates a single link for a given user and id. Parameters ^^^^^^^^^^ * Name userUid * Name id

DeleteByIdAndUserUid

DELETE <base_url>/userlinks/:userUid/links/{id}

Authentication: Required

Deletes the link for the given user and id. Parameters ^^^^^^^^^^ * Name userUid * Name id

social_services › Globals

social_services

---

title: “Social Services” date: 2019-07-02T22:39:37.238Z

A service that provides social features to users including a social profile, online presence, friends list, blocked players list and player-to-player messaging.

Getting Started

To get started using this service first clone the source. It is highly recommended that you fork the project first.

git clone https://gitlab.com/AcceleratXR/Core/social_services.git

Running the Service

Open up a new shell to the cloned folder and build the Docker image using docker-compose.

docker-compose build

You can now run the server with the following command.

docker-compose up

Debugging

Visual Studio Code is the recommended IDE to develop with. The project includes workspace and launch configuration files out of the box.

To debug while running via Docker Compose select the Docker: Attach Debugger configuration and hit the F5 key. If you want to run the server directly and debug choose the Launch Server configuration.

social_services › Globals

social_services

Index

Classes

• AuthToken

• Count

• Message

• MessageRoute

• MetricsCollector

• Profile

• ProfileRoute

• UserLink

• UserLinkRoute

Variables

• bgManager

• cliDefinitions

• cliOptions

• conf

• logger

• packageInfo

• server

Functions

• start

Variables

Let bgManager

• bgManager: BackgroundServiceManager | undefined = undefined

Defined in src/server.ts:20

---

Const cliDefinitions

• cliDefinitions: OptionDefinition[] = []

Defined in src/server.ts:17

---

Const cliOptions

• cliOptions: CommandLineOptions = commandLineArgs(cliDefinitions)

Defined in src/server.ts:18

---

Const conf

• conf: any = require(”nconf”) .argv() .env({ separator: “__”, parseValues: true, })

Defined in src/config.ts:5

---

Const logger

• logger: any = Logger()

Defined in src/server.ts:14

---

Const packageInfo

• packageInfo: any = require(”../package.json”)

Defined in src/config.ts:4

---

Let server

• server: Server | undefined = undefined

Defined in src/server.ts:19

Functions

Const start

▸ start(config: any, logger: any): Promise‹void›

Defined in src/server.ts:22

Parameters:

Name | Type | —— | —— | config | any | logger | any |

Returns: Promise‹void›