together.*

Type library
Revision Current Public Version 1.1
Keywords together
Sample code github samples
See also http://playstogether.com
Availability Starter, Basic, Pro

Overview

The Together class is the root class in the Together api. It contains essential configuration settings, an object representing the logged in User, and various Managers for creating, deleting, and retrieving various Together objects.

Sign Up

To use the Together service, please sign up for an account.

Platforms

Syntax

It is best to assign the GetInstance call to a global either you have created or to the declared global in the library, "g_Together". After signing up you can connect/login by passing your generated keys to the initialization call of the created instance.

local together = require("plugin.together");
g_Together = together:GetInstance();
g_Together:Initialize(yourPublicKey, yourPrivateKey, yourGameKey, yourPlatform);

Callbacks

All network methods that require a callback function will invoke your callback with the same object. Details about this "Event" object can be found here.

Project Settings

SDK

When you build using the Corona Simulator, the server automatically takes care of integrating the plugin into your project.

All you need to do is add an entry into a plugins table of your build.settings. The following is an example of a minimal build.settings file:

settings =
{
    plugins =
    {
        -- key is the name passed to Lua's 'require()'
        ["plugin.together"] =
        {
            -- required
            publisherId = "com.playstogether",
        },
    },      
}

Sample Code

You can access sample projects from the Git repository here.

Follow this tutorial for getting started quickly and making your own memory game.

Support

More support is available from the Playstogether team:

Managers

TogetherCache TogetherCache

A TogetherCache class instance used to Load and Save the together cache on the Device.

TogetherSocial Social

A TogetherSocial class instance containing various social apis.

GameInstanceManager GameInstanceManager

A GameInstanceManager class instance useful for storing GameInstances the logged in User is a member of.

LeaderboardManager LeaderboardManager

A LeaderboardManager class instance useful for storing Leaderboards.

UserMessageManager UserMessageManager

A UserMessageManager class instance for sending and receiving in game messages or emails

UserNotificationManager UserNotificationManager

A UserNotificationManager class instance useful for storing UserNotifications.

AchievementManager AchievementManager

A AchievementManager class instance useful for storing Achievements.

ItemManager ItemManager

A ItemManager class instance useful for storing Items.

ChatRoomManager ChatRoomManager

A ChatRoomManager class instance useful for storing ChatRooms.

FriendManager FriendManager

A FriendManager class instance useful for storing together Friends.

UserPurchaseManager UserPurchaseManager

A UserPurchaseManager class instance useful for storing UserPurchases.

Members

number PingInterval

How often the ping message is sent to the server.

number LastPingTime

The last time a ping message was sent to the server.

string ApnsDeviceToken

The DeviceToken for Apple push notifications.

boolean RegisteredPushEnabledDevice

A boolean indicates whether the push enabled Device has been registered with the server.

string CacheUserGuid

The cached UserGuid of the last logged in User.

string TogetherServerIP

The IP address of the together server.

string ClientPublicKey

The PublicKey of the Together Client the Game belongs to.

string ClientPrivateKey

The PrivateKey of the Together Client that Game belongs to.

string GameKey

The Key of the Together Game.

string PlatformName

The name of the platform the Game is running on. (IOS, Android, Mac OS, Unity, HTML5/JS)

string FacebookAppID

The ApplicationID of the Facebook application.

string FacebookPrivileges

The Facebook privileges to ask for when logging into Facebook.

TogetherUser TogetherUser

A TogetherUser class instance representing the logged in User.

TogetherUserSession TogetherUserSession

A TogetherUserSession class instance representing the logged in UserSession.

Methods

GetInstance()

Gets or creates the instance of global 'g_Together'

Syntax

Together:GetInstance(  )

GetUserID()

Shorthand for fetching the TogetherUser.UserID property.

Syntax

Together:GetUserID(  )

GetUsername()

Shorthand for fetching the TogetherUser.Username property.

Syntax

Together:GetUsername(  )

GetNameOfUser()

Shorthand for fetching the TogetherUser.Name property.

Syntax

Together:GetNameOfUser(  )

GetUserViewName()

Shorthand for calling the TogetherUser:GetViewName method.

Syntax

Together:GetUserViewName(  )

IsUserFacebookRegistered()

Checks to see if the User is registered via Facebook.

Syntax

Together:IsUserFacebookRegistered(  )

IsUserCustomRegistered()

Checks to see if the User is registered via Custom.

Syntax

Together:IsUserCustomRegistered(  )

FindTogetherFriendByUserID()

Finds the TogetherFriend with the specified UserID.

Syntax

Together:FindTogetherFriendByUserID( userID )

Parameters

number userID

The ID of User to retrieve.

FindTogetherFriendBySocialID()

Finds the TogetherFriend with the specified SocialID (FacebookID). Finds the FacebookFriend with the specified SocialID (FacebookID).

Syntax

Together:FindTogetherFriendBySocialID( userID, userID )

Parameters

number userID

The ID of User to retrieve.

number userID

The ID of User to retrieve.

GetSessionToken()

Gets the session token returned when the User logged in.

Syntax

Together:GetSessionToken(  )

Initialize()

Initializes the Together class so it's ready to make API requests.

Syntax

Together:Initialize( clientPublicKey, clientPrivateKey, gameKey, platformName )

Parameters

string clientPublicKey

The PublicKey assigned to your account. This is accessible from the playstogether developer portal.

string clientPrivateKey

The PrivateKey assigned to your account. This is accessible from the playstogether developer portal.

string gameKey

The GameKey of the game you are connecting to. This is accessible from the playstogether developer portal.

string platformName

The Name of the Platform the game is running on. Supported Platforms are:
("IOS", "Android", "Mac OS", "Unity", "HTML5/JS")

SetApnsDeviceToken()

Sets the ApnsDeviceToken that will be used when registering the device for push notifications.

Syntax

Together:SetApnsDeviceToken( apnsDeviceToken )

Parameters

string apnsDeviceToken

The device token.

SetServerAddress()

Sets the ServerAddress all network messages will be sent to when talking to the together servers. This defaults to the primary Together servers and does not need to be called unless you are working with a form of private/local server instance. If you are interested in private hosting and want more information, contact .

Syntax

Together:SetServerAddress( serverAddress )

Parameters

string serverAddress

The server address of the together server.

GetServerAddress()

Gets the ServerAddress all requests are being sent to.

Syntax

Together:GetServerAddress(  )

SetFacebookAppID()

Sets the Facebook ApplicationID all Facebook related calls will use.

Syntax

Together:SetFacebookAppID( facebookAppID, facebookPrivileges )

Parameters

string facebookAppID

The ApplicationID of the Facebook application.

table facebookPrivileges

A table full of Facebook privileges to ask for when logging into Facebook.

GetCacheUserGuid()

Gets the cached UserGuid.

Syntax

Together:GetCacheUserGuid(  )

LoadTogetherCache()

Loads the Together Cache from the Device. The only thing stored in the TogetherCache currently is the UserGuid of the last logged in user for the application.

Syntax

Together:LoadTogetherCache(  )

SaveTogetherCache()

Saves the Together Cache to the Device. The only thing stored in the TogetherCache currently is the UserGuid of the last logged in user for the application.

Syntax

Together:SaveTogetherCache(  )

EraseTogetherCache()

Erases the Together Cache from the Device. The only thing stored in the TogetherCache currently is the UserGuid of the last logged in user for the application.

Syntax

Together:EraseTogetherCache(  )

LoginUser()

Logs in the User. This should always be the first Together network message called. If no User GUID is provided, a new user account will be created anonymously and assigned a GUID which can be used to log the user in again later or register them with Facebook or via Custom form.

Note Currently anonymous users will NOT be deleted. However it is possible that a user cleansing system will be implemented in the future that removes unregistered accounts after 3 to 6 months of inactivity.

Syntax

Together:LoginUser( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

GetServerTimeUTC()

Gets the Server Timestamp(UTC+0). The timestamp will be returned in the data member of the callback as a long.

Syntax

Together:GetServerTimeUTC( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

GetGlobalProfile()

Fetches your developer global profile of data set through the portal or by atomic operations. The callback object will contain the profile in the data member as a PropertyCollection type.

Syntax

Together:GetGlobalProfile( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

GetGameProfile()

Fetches the game's profile of data set through the portal or by atomic operations. The callback object will contain the profile in the data member as a PropertyCollection type.

Syntax

Together:GetGameProfile( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

GetUserProfile()

Fetches the current, logged in user's profile for the game. The callback object will contain the profile in the data member as a PropertyCollection type. This is also retrieved when the User object for the local player is fetched and can be modified with the User.Modify() call.

Syntax

Together:GetUserProfile( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

AddAtomic()

Adds an atomic field to either the game profile or the global profile. The callback object will contain a Property type in the data field.

Syntax

Together:AddAtomic( global, parentName, propertyName, propertyValue, callbackFunc )

Parameters

boolean global

Pass TRUE to add the atomic entry to the global profile, FALSE to add it to the game profile

string parentName

The name of an existing parent collection in which to add the atomic entry to

string propertyName

The name of the atomic field to add

string propertyValue

The value of the atomic entry to apply

function callbackFunc

The function to call upon completion.

IncrementAtomic()

Increments an existing atomic property in either the game profile or global profile without an upper limit. The callback object will contain a Property type in the data field.

Syntax

Together:IncrementAtomic( global, parentName, propertyName, callbackFunc )

Parameters

boolean global

Pass TRUE to increment an entry in the global profile, FALSE to increment an entry in the game profile

string parentName

The name of an existing parent collection containing the property

string propertyName

The name of the property to increment

function callbackFunc

The function to call upon completion.

IncrementAtomicWithLimit()

Increments an existing atomic property in either the game profile or global profile with a passed upper limit. The callback object will contain a Property type in the data field.

Syntax

Together:IncrementAtomicWithLimit( global, parentName, propertyName, limit, callbackFunc )

Parameters

boolean global

Pass TRUE to increment an entry in the global profile, FALSE to increment an entry in the game profile

string parentName

The name of an existing parent collection containing the property

string propertyName

The name of the property to increment

number limit

The upper limit of the atomic operation as an integer

function callbackFunc

The function to call upon completion.

IncrementAtomicWithLimitRef()

Increments an existing atomic property in either the game profile or global profile with a reference to a limit elsewhere in the profile. The callback object will contain a Property type in the data field.

Syntax

Together:IncrementAtomicWithLimitRef( global, parentName, propertyName, refParent, refProperty, callbackFunc )

Parameters

boolean global

Pass TRUE to increment an entry in the global profile, FALSE to increment an entry in the game profile

string parentName

The name of an existing parent collection containing the property

string propertyName

The name of the property to increment

string refParent

The name of the parent collection containing the property to be used as the limit

string refProperty

The name of the property in the referenced parent to be used as the limit

function callbackFunc

The function to call upon completion.

RegisterFacebook()

Registers the User with Facebook. TogetherSocialFacebook:Login() calls this method upon successfully logging into facebook.

Syntax

Together:RegisterFacebook( facebookID, name, firstName, lastName, link, username, gender, locale, callbackFunc )

Parameters

string facebookID

The FacebookID of the facebook user.

string name

The name of the facebook user.

string firstName

The first name of the facebook user.

string lastName

The last name of the facebook user.

string link

The link to the facebook user.

string username

The username of the facebook user.

string gender

The gender of the facebook user.

string locale

The locale of the facebook user.

function callbackFunc

The function to call upon completion.

RegisterCustom()

Registers the User with the custom registration system.

Syntax

Together:RegisterCustom( email, password, name, callbackFunc )

Parameters

string email

The email of the Custom user.

string password

The password of the Custom user.

string name

The name of the Custom user.

function callbackFunc

The function to call upon completion.

Logout()

Logs out the User. If the user did not registered, this will mark the account inactive but is reactivated at the next login with the same user GUID.

Note Currently anonymous users will NOT be deleted. However it is possible that a user cleansing system will be implemented in the future that removes unregistered accounts after 3 to 6 months of inactivity.

Syntax

Together:Logout( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

RegisterPushEnabledDevice()

Registers a push enabled Device. Use by setting ApnsDeviceToken and/or GcmDeviceToken and/or WnsDeviceToken first then calling.

Syntax

Together:RegisterPushEnabledDevice( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

SendPushNotification()

Sends a push notification message.

Note This counts towards Push Notifications on your developer account and does not count as a System Request.

Syntax

Together:SendPushNotification( destUserID, notificationMessage, platform, data, callbackFunc )

Parameters

number destUserID

The ID of the User to send the push notification to.

string notificationMessage

The message to send.

string platform

the platform that the message is being sent to: ios or android

TogetherNotification data

the TogetherNotification to be sent to the server

function callbackFunc

The function to call upon completion.

Ping()

Pings the Server for the User as a keep-alive.

Syntax

Together:Ping( callbackFunc )

Parameters

function callbackFunc

The function to call upon completion.

AddAnalytic()

Adds an Analytic event for the User with simple options.

Syntax

Together:AddAnalytic( eventName, propName, propValue, callbackFunc )

Parameters

string eventName

The name of the event to assign to the analytic record.

string propName

The name of the property to assign to the analytic record.

string propValue

The value of the property to assign to the analytic record.

function callbackFunc

The function to call upon completion.

AddAnalyticEx()

Adds an Analytic event for the User with extended options.

Syntax

Together:AddAnalyticEx( eventName, propertyCollection, callbackFunc )

Parameters

string eventName

The name of the event to assign to the analytic record.

PropertyCollection propertyCollection

Collection of data to add to the event record

function callbackFunc

The function to call upon completion.