Package host.anzo.eossdk.eos.sdk

Class EOS_Connect_Interface

java.lang.Object
com.sun.jna.PointerType
host.anzo.eossdk.eos.sdk.EOS_Connect_Interface
All Implemented Interfaces:
com.sun.jna.NativeMapped
public class EOS_Connect_Interface extends com.sun.jna.PointerType
The Connect Interface is used to manage local user permissions and access to backend services through the verification of various forms of credentials. It creates an association between third party providers and an internal mapping that allows Epic Online Services to represent a user agnostically. All Connect Interface calls take a handle of type EOS_HConnect as the first parameter. This handle can be retrieved from a EOS_HPlatform handle by using the EOS_Platform_GetConnectInterface function.
Since:
8/9/2023
See Also:

  • Field Details

    • EOS_CONNECT_EXTERNAL_ACCOUNT_ID_MAX_LENGTH

      public static final int EOS_CONNECT_EXTERNAL_ACCOUNT_ID_MAX_LENGTH
      Max length of an external account ID in string form
      See Also:

  • Constructor Details

    • EOS_Connect_Interface

      public EOS_Connect_Interface(com.sun.jna.Pointer address)

    • EOS_Connect_Interface

      public EOS_Connect_Interface()

  • Method Details

    • login

      public void login(EOS_Connect_LoginOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnLoginCallback completionDelegate)
      Login/Authenticate given a valid set of external auth credentials.
      Parameters:
      options - structure containing the external account credentials and type to use during the login operation.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the login operation completes, either successfully or in error.

    • createUser

      public void createUser(EOS_Connect_CreateUserOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnCreateUserCallback completionDelegate)
      Create an account association with the Epic Online Service as a product user given their external auth credentials.
      Parameters:
      options - structure containing a continuance token from a "user not found" response during Login (always try login first).
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the create operation completes, either successfully or in error.

    • linkAccount

      public void linkAccount(EOS_Connect_LinkAccountOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnLinkAccountCallback completionDelegate)
      Link a set of external auth credentials with an existing product user on the Epic Online Service.
      Parameters:
      options - structure containing a continuance token from a "user not found" response during Login (always try login first) and a currently logged in user not already associated with this external auth provider.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the link operation completes, either successfully or in error.

    • unlinkAccount

      public void unlinkAccount(EOS_Connect_UnlinkAccountOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnUnlinkAccountCallback completionDelegate)
      Unlink external auth credentials from the owning keychain of a logged in product user.

      This function allows recovering the user from scenarios where they have accidentally proceeded to creating a new product user for the local native user account, instead of linking it with an existing keychain that they have previously created by playing the game (or another game owned by the organization) on another platform.

      In such scenario, after the initial platform login and a new product user creation, the user wishes to re-login using other set of external auth credentials to connect with their existing game progression data. In order to allow automatic login also on the current platform, they will need to unlink the accidentally created new keychain and product user and then use the EOS_Connect_Login and EOS_Connect_LinkAccount APIs to link the local native platform account with that previously created existing product user and its owning keychain.

      In another scenario, the user may simply want to disassociate the account that they have logged in with from the current keychain that it is linked with, perhaps to link it against another keychain or to separate the game progressions again.

      In order to protect against account theft, it is only possible to unlink user accounts that have been authenticated and logged in to the product user in the current session. This prevents a malicious actor from gaining access to one of the linked accounts and using it to remove all other accounts linked with the keychain. This also prevents a malicious actor from replacing the unlinked account with their own corresponding account on the same platform, as the unlinking operation will ensure that any existing authentication session cannot be used to re-link and overwrite the entry without authenticating with one of the other linked accounts in the keychain. These restrictions limit the potential attack surface related to account theft scenarios.

      Parameters:
      options - structure containing operation input parameters.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the unlink operation completes, either successfully or in error.

    • createDeviceId

      public void createDeviceId(EOS_Connect_CreateDeviceIdOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnCreateDeviceIdCallback completionDelegate)
      Create a new unique pseudo-account that can be used to identify the current user profile on the local device.

      This function is intended to be used by mobile games and PC games that wish to allow a new user to start playing without requiring to login to the game using any user identity. In addition to this, the Device ID feature is used to automatically login the local user also when they have linked at least one external user account(s) with the local Device ID.

      It is possible to link many devices with the same user's account keyring using the Device ID feature.

      Linking a device later or immediately with a real user account will ensure that the player will not lose their progress if they switch devices or lose the device at some point, as they will be always able to login with one of their linked real accounts and also link another new device with the user account associations keychain. Otherwise, without having at least one permanent user account linked to the Device ID, the player would lose all of their game data and progression permanently should something happen to their device or the local user profile on the device.

      After a successful one-time CreateDeviceId operation, the game can login the local user automatically on subsequent game starts with EOS_Connect_Login using the EOS_ECT_DEVICEID_ACCESS_TOKEN credentials type. If a Device ID already exists for the local user on the device then EOS_DuplicateNotAllowed error result is returned and the caller should proceed to calling EOS_Connect_Login directly.

      Parameters:
      options - structure containing operation input parameters.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the create operation completes, either successfully or in error.

    • deleteDeviceId

      public void deleteDeviceId(EOS_Connect_DeleteDeviceIdOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnDeleteDeviceIdCallback completionDelegate)
      Delete any existing Device ID access credentials for the current user profile on the local device.

      The deletion is permanent and it is not possible to recover lost game data and progression if the Device ID had not been linked with at least one real external user account.

      On Android and iOS devices, uninstalling the application will automatically delete any local Device ID credentials created by the application.

      On Desktop platforms (Linux, macOS, Windows), Device ID credentials are not automatically deleted. Applications may re-use existing Device ID credentials for the local OS user when the application is re-installed, or call the DeleteDeviceId API on the first run to ensure a fresh start for the user.

      Parameters:
      options - structure containing operation input parameters
      clientData - arbitrary data that is passed back to you in the CompletionDelegate
      completionDelegate - a callback that is fired when the delete operation completes, either successfully or in error

    • transferDeviceIdAccount

      public void transferDeviceIdAccount(EOS_Connect_TransferDeviceIdAccountOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnTransferDeviceIdAccountCallback completionDelegate)
      Transfer a Device ID pseudo-account and the product user associated with it into another keychain linked with real user accounts (such as Epic Games, PlayStation(TM)Network, Xbox Live, and other).

      This function allows transferring a product user, i.e. the local user's game progression backend data from a Device ID owned keychain into a keychain with real user accounts linked to it. The transfer of Device ID owned product user into a keychain of real user accounts allows persisting the user's game data on the backend in the event that they would lose access to the local device or otherwise switch to another device or platform.

      This function is only applicable in the situation of where the local user first plays the game using the anonymous Device ID login, then later logs in using a real user account that they have also already used to play the same game or another game under the same organization within Epic Online Services. In such situation, while normally the login attempt with a real user account would return EOS_InvalidUser and an EOS_ContinuanceToken and allow calling the EOS_Connect_LinkAccount API to link it with the Device ID's keychain, instead the login operation succeeds and finds an existing user because the association already exists. Because the user cannot have two product users simultaneously to play with, the game should prompt the user to choose which profile to keep and which one to discard permanently. Based on the user choice, the game may then proceed to transfer the Device ID login into the keychain that is persistent and backed by real user accounts, and if the user chooses so, move the product user as well into the destination keychain and overwrite the existing previous product user with it. To clarify, moving the product user with the Device ID login in this way into a persisted keychain allows to preserve the so far only locally persisted game progression and thus protect the user against a case where they lose access to the device.

      On success, the completion callback will return the preserved EOS_ProductUserId that remains logged in while the discarded EOS_ProductUserId has been invalidated and deleted permanently. Consecutive logins using the existing Device ID login type or the external account will connect the user to the same backend data belonging to the preserved EOS_ProductUserId.

      Example walkthrough: Cross-platform mobile game using the anonymous Device ID login.

      For onboarding new users, the game will attempt to always automatically login the local user by calling EOS_Connect_Login using the EOS_ECT_DEVICEID_ACCESS_TOKEN login type. If the local Device ID credentials are not found, and the game wants a frictionless entry for the first time user experience, the game will automatically call EOS_Connect_CreateDeviceId to create new Device ID pseudo-account and then login the local user into it. Consecutive game starts will thus automatically login the user to their locally persisted Device ID account.

      The user starts playing anonymously using the Device ID login type and makes significant game progress. Later, they login using an external account that they have already used previously for the same game perhaps on another platform, or another game owned by the same organization. In such case, EOS_Connect_Login will automatically login the user to their existing account linking keychain and create automatically a new empty product user for this product.

      In order for the user to use their existing previously created keychain and have the locally created Device ID login reference to that keychain instead, the user's current product user needs to be moved to be under that keychain so that their existing game progression will be preserved. To do so, the game can call EOS_Connect_TransferDeviceIdAccount to transfer the Device ID login and the product user associated with it into the other keychain that has real external user account(s) linked to it. Note that it is important that the game either automatically checks that the other product user does not have any meaningful progression data, or otherwise will prompt the user to make the choice on which game progression to preserve and which can be discarded permanently. The other product user will be discarded permanently and cannot be recovered, so it is very important that the user is guided to make the right choice to avoid accidental loss of all game progression.

      Parameters:
      options - structure containing the logged in product users and specifying which one will be preserved.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the transfer operation completes, either successfully or in error.
      See Also:

    • queryExternalAccountMappings

      public void queryExternalAccountMappings(EOS_Connect_QueryExternalAccountMappingsOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnQueryExternalAccountMappingsCallback completionDelegate)
      Retrieve the equivalent Product User IDs from a list of external account IDs from supported account providers. The values will be cached and retrievable through EOS_Connect_GetExternalAccountMapping.

      A common use case is to query other users who are connected through the same account system as the local user. Queries using external account IDs of another account system may not be available, depending on the account system specifics.

      Parameters:
      options - structure containing a list of external account IDs, in string form, to query for the Product User ID representation.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the query operation completes, either successfully or in error.

    • queryProductUserIdMappings

      public void queryProductUserIdMappings(EOS_Connect_QueryProductUserIdMappingsOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnQueryProductUserIdMappingsCallback completionDelegate)
      Retrieve the equivalent external account mappings from a list of Product User IDs.

      The values will be cached and retrievable via EOS_Connect_GetProductUserIdMapping, EOS_Connect_CopyProductUserExternalAccountByIndex, EOS_Connect_CopyProductUserExternalAccountByAccountType or EOS_Connect_CopyProductUserExternalAccountByAccountId.

      Parameters:
      options - structure containing a list of Product User IDs to query for the external account representation.
      clientData - arbitrary data that is passed back to you in the CompletionDelegate.
      completionDelegate - a callback that is fired when the query operation completes, either successfully or in error.
      See Also:

    • getExternalAccountMapping

      public EOS_ProductUserId getExternalAccountMapping(EOS_Connect_GetExternalAccountMappingsOptions options)
      Fetch a Product User ID that maps to an external account ID cached from a previous query.
      Parameters:
      options - structure containing the local user and target external account ID.
      Returns:
      The Product User ID, previously retrieved from the backend service, for the given target external account.

    • getProductUserIdMapping

      public String getProductUserIdMapping(EOS_Connect_GetProductUserIdMappingOptions options) throws EOSException
      Fetch an external account ID, in string form, that maps to a given Product User ID.
      Parameters:
      options - structure containing the local user and target Product User ID.
      Returns:
      external account ID data
      Throws:
      EOSInvalidParametersException - if you pass a null pointer for the out parameter.
      EOSNotFoundException - if the mapping doesn't exist or hasn't been queried yet.
      EOSLimitExceededException - if the OutBuffer is not large enough to receive the external account ID. InOutBufferLength contains the required minimum length to perform the operation successfully.
      EOSException

    • getProductUserExternalAccountCount

      public int getProductUserExternalAccountCount(EOS_Connect_GetProductUserExternalAccountCountOptions options)
      Fetch the number of linked external accounts for a Product User ID.
      Parameters:
      options - The Options associated with retrieving the external account info count.
      Returns:
      Number of external accounts or 0 otherwise.
      See Also:

    • copyProductUserExternalAccountByIndex

      public EOS_Connect_ExternalAccountInfo copyProductUserExternalAccountByIndex(EOS_Connect_CopyProductUserExternalAccountByIndexOptions options) throws EOSException
      Fetch information about an external account linked to a Product User ID. On a successful call, the caller must release the returned structure using the EOS_Connect_ExternalAccountInfo_Release API.
      Parameters:
      options - Structure containing the target index.
      Returns:
      The external account info data for the user with given index.
      Throws:
      EOSInvalidParametersException - if you pass a null pointer for the out parameter.
      EOSNotFoundException - if the account data doesn't exist or hasn't been queried yet.
      EOSException
      See Also:

    • copyProductUserExternalAccountByAccountType

      public EOS_Connect_ExternalAccountInfo copyProductUserExternalAccountByAccountType(EOS_Connect_CopyProductUserExternalAccountByAccountTypeOptions options) throws EOSException
      Fetch information about an external account of a specific type linked to a Product User ID. On a successful call, the caller must release the returned structure using the EOS_Connect_ExternalAccountInfo_Release API.
      Parameters:
      options - Structure containing the target external account type.
      Returns:
      The external account info data for the user with given external account type.
      Throws:
      EOSInvalidParametersException - if you pass a null pointer for the out parameter.
      EOSNotFoundException - if the account data doesn't exist or hasn't been queried yet.
      EOSException
      See Also:

    • copyProductUserExternalAccountByAccountId

      public EOS_Connect_ExternalAccountInfo copyProductUserExternalAccountByAccountId(EOS_Connect_CopyProductUserExternalAccountByAccountIdOptions options) throws EOSException
      Fetch information about an external account linked to a Product User ID. On a successful call, the caller must release the returned structure using the EOS_Connect_ExternalAccountInfo_Release API.
      Parameters:
      options - Structure containing the target external account ID.
      Returns:
      The external account info data for the user with given external account ID.
      Throws:
      EOSInvalidParametersException - if you pass a null pointer for the out parameter.
      EOSNotFoundException - if the account data doesn't exist or hasn't been queried yet.
      EOSException
      See Also:

    • copyProductUserInfo

      public EOS_Connect_ExternalAccountInfo copyProductUserInfo(EOS_Connect_CopyProductUserInfoOptions options) throws EOSException
      Fetch information about a Product User, using the external account that they most recently logged in with as the reference. On a successful call, the caller must release the returned structure using the EOS_Connect_ExternalAccountInfo_Release API.
      Parameters:
      options - Structure containing the target external account ID.
      Returns:
      The external account info data last logged in for the user.
      Throws:
      EOSInvalidParametersException - if you pass a null pointer for the out parameter.
      EOSNotFoundException - if the account data doesn't exist or hasn't been queried yet.
      EOSException
      See Also:

    • getLoggedInUsersCount

      public int getLoggedInUsersCount()
      Fetch the number of product users that are logged in.
      Returns:
      the number of product users logged in.

    • getLoggedInUserByIndex

      public EOS_ProductUserId getLoggedInUserByIndex(int index)
      Fetch a Product User ID that is logged in. This Product User ID is in the Epic Online Services namespace.
      Parameters:
      index - an index into the list of logged in users. If the index is out of bounds, the returned Product User ID will be invalid.
      Returns:
      the Product User ID associated with the index passed.

    • getLoginStatus

      public EOS_ELoginStatus getLoginStatus(EOS_ProductUserId localUserId)
      Fetches the login status for an Product User ID. This Product User ID is considered logged in as long as the underlying access token has not expired.
      Parameters:
      localUserId - the Product User ID of the user being queried.
      Returns:
      the enum value of a user's login status.

    • addNotifyAuthExpiration

      public EOS_NotificationId addNotifyAuthExpiration(EOS_Connect_AddNotifyAuthExpirationOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnAuthExpirationCallback notification)
      Register to receive upcoming authentication expiration notifications. Notification is approximately 10 minutes prior to expiration. Call EOS_Connect_Login again with valid third party credentials to refresh access.

      Must call removeNotifyAuthExpiration(EOS_NotificationId) to remove the notification.

      Parameters:
      options - structure containing the API version of the callback to use.
      clientData - arbitrary data that is passed back to you in the callback.
      notification - a callback that is fired when the authentication is about to expire.
      Returns:
      handle representing the registered callback.

    • removeNotifyAuthExpiration

      public void removeNotifyAuthExpiration(EOS_NotificationId inId)
      Unregister from receiving expiration notifications.
      Parameters:
      inId - handle representing the registered callback.

    • addNotifyLoginStatusChanged

      public EOS_NotificationId addNotifyLoginStatusChanged(EOS_Connect_AddNotifyLoginStatusChangedOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnLoginStatusChangedCallback notification)
      Register to receive user login status updates.
      Must call removeNotifyLoginStatusChanged(EOS_NotificationId) to remove the notification.
      Parameters:
      options - structure containing the API version of the callback to use.
      clientData - arbitrary data that is passed back to you in the callback.
      notification - a callback that is fired when the login status for a user changes.
      Returns:
      handle representing the registered callback.

    • removeNotifyLoginStatusChanged

      public void removeNotifyLoginStatusChanged(EOS_NotificationId inId)
      Unregister from receiving user login status updates.
      Parameters:
      inId - handle representing the registered callback.

    • copyIdToken

      public EOS_Connect_IdToken copyIdToken(EOS_Connect_CopyIdTokenOptions options) throws EOSException
      Fetches an ID token for a Product User ID.
      Parameters:
      options - Structure containing information about the ID token to copy.
      Returns:
      The ID token for the given user, if it exists and is valid; use EOS_Connect_IdToken_Release when finished.
      Throws:
      EOSInvalidParametersException - if you pass a null pointer for the out parameter.
      EOSNotFoundException - if the ID token is not found or expired.
      EOSException
      See Also:

    • verifyIdToken

      public void verifyIdToken(EOS_Connect_VerifyIdTokenOptions options, com.sun.jna.Pointer clientData, EOS_Connect_OnVerifyIdTokenCallback completionDelegate)
      Verify a given ID token for authenticity and validity.
      Parameters:
      options - structure containing information about the ID token to verify.
      clientData - arbitrary data that is passed back to you in the callback.
      completionDelegate - a callback that is fired when the operation completes, either successfully or in error.