backup push

fnal/api/siwg.api

@@ -0,0 +1,199 @@
+- 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.