SIWG-Extension/siwg/api/siwg.api

- name: siwg
  type: table
  desc: Functions and constants for interacting with Google Services (SIWG) APIs

  members:

#*****************************************************************************************************

  - name: is_supported
    type: function
    desc: Check if Google Services are available & ready on the device.

    returns:
      - name: is_supported
        type: boolean
        desc: Status of Google Services on the device.

    examples:
      - desc: |-
            ```lua
            if siwg then
              local is_supported = siwg.is_supported()
            end
            ```

#*****************************************************************************************************

  - name: login
    type: function
    desc: Login to SIWG using a button.

    examples:
      - desc: |-
            Log in to SIWG using a button:
            ```lua
            if siwg then
              siwg.login()
            end
            ```

#*****************************************************************************************************

  - name: silent_login
    type: function
    desc: Silent login to SIWG.

          This function is trying to retrieve the currently signed-in player’s account.

          [icon:attention] By default login methods request `GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN`.
          But if you use Disk, we have to request extra scope `Drive.SCOPE_APPFOLDER`.
          Or if you use ID token, we have to request ID token with provided client_id.
          If so it causes the first time silent sign-in to fail, except for users who
          have already signed in successfully on a different device. Turn off SIWG
          features you don't want to use in `game.project`.

    examples:
      - desc: |-
            ```lua
            function init(self)
              if siwg then
                siwg.silent_login()
              end
            end
            ```

#*****************************************************************************************************

  - name: logout
    type: function
    desc: Logout from SIWG

    examples:
      - desc: |-
            ```lua
            if siwg then
              siwg.logout()
            end
            ```

#*****************************************************************************************************

  - name: get_display_name
    type: function
    desc: Get the current SIWG player display name.

    returns:
      - name: name
        type: string
        desc: The player's display name.

    examples:
      - desc: |-
            ```lua
            if siwg then
              local name = siwg.get_display_name()
            end
            ```

#*****************************************************************************************************

  - name: get_id
    type: function
    desc: Get the current SIWG player id.

    returns:
      - name: id
        type: string
        desc: The player ID.

    examples:
      - desc: |-
            ```lua
            if siwg then
              local id = siwg.get_id()
            end
            ```

#*****************************************************************************************************

  - name: get_id_token
    type: function
    desc: Get the current SIWG player id token. Available only if "siwg.client_id" is configured in game.project
          and "siwg.request_id_token = 1".

    returns:
      - name: id_token
        type: string
        desc: The player ID token.

    examples:
      - desc: |-
            ```lua
            if siwg then
              local id_token = siwg.get_id_token()
            end
            ```

#*****************************************************************************************************

  - name: get_server_auth_code
    type: function
    desc: Returns a one-time server auth code to send to your web server which can be exchanged for access token

    returns:
      - name: server_auth_code
        type: string
        desc: The server auth code for logged in account.

    examples:
      - desc: |-
            ```lua
            if siwg then
              local server_auth_code = siwg.get_server_auth_code()
            end
            ```

#*****************************************************************************************************

  - name: is_logged_in
    type: function
    desc: Check if a user is logged in currently.

    returns:
      - name: is_loggedin
        type: boolean
        desc: Current login state.

    examples:
      - desc: |-
            ```lua
            if siwg then
              local is_loggedin = siwg.is_logged_in()
            end
            ```

#*****************************************************************************************************

  - name: MSG_SIGN_IN
    type: number
    desc: The message type that SIWG sends when finishing the asynchronous operation
          after calling `siwg.login()`

  - name: MSG_SILENT_SIGN_IN
    type: number
    desc: The message type that SIWG sends when finishing the asynchronous operation
          after calling `siwg.silent_login()`

  - name: MSG_SIGN_OUT
    type: number
    desc: The message type that SIWG sends when finishing the asynchronous operation
          after calling `siwg.logout()`

  - name: STATUS_SUCCESS
    type: number
    desc: An operation success.

  - name: STATUS_FAILED
    type: number
    desc: An operation failed. Check the error field in the massage table.