add API documentation

defold · Apr 9, 2024 · 84b8ad1 · 84b8ad1
1 parent 719350d
commit 84b8ad1
Show file tree

Hide file tree

Showing 5 changed files with 699 additions and 191 deletions.
diff --git a/facebook/api/facebook.script_api b/facebook/api/facebook.script_api
@@ -75,6 +75,77 @@
             end)
             ```
 
+#*****************************************************************************************************
+
+  - name: login_with_tracking_preference
+    type: function
+    desc: iOS ONLY. Login to Facebook and request a set of permissions. Allows developers to signal that a login is limited in terms of tracking users.
+
+          The user is prompted to authorize the application using the login dialog of the specific
+          platform. Even if the user is already logged in to Facebook this function can still be used to request additional publish permissions.
+
+          A comprehensive list of permissions can be found in the [Facebook permissions](https://developers.facebook.com/docs/facebook-login/permissions) documentation,
+          as well as in their [guide to best practices for login management](https://developers.facebook.com/docs/facebook-login/best-practices).
+          For Limited Login the list of permissions can be found in the [Permissions in Limited Login](https://developers.facebook.com/docs/facebook-login/limited-login/permissions) documentation.
+
+    parameters:
+      - name: login_tracking
+        type: number
+        desc: The tracking type for the login.
+              Can be any of
+
+                - `facebook.LOGIN_TRACKING_LIMITED`
+
+                - `facebook.LOGIN_TRACKING_ENABLED`
+      - name: permissions
+        type: table
+        desc: table with the requested publish permission strings.
+      - name: crypto_nonce
+        type: string
+        desc: Nonce that the configuration was created with. A unique nonce will be used if none is provided to the factory method.
+
+      - name: callback
+        type: function
+        desc: Callback function that is executed when the permission request dialog is closed.
+        parameters:
+          - name: self
+            type: object
+            desc: The context of the calling script
+
+          - name: data
+            type: table
+            desc: A table that contains the response
+
+    examples:
+      - desc: |-
+            Log in to Facebook with a set of publish permissions
+            ```lua
+            local permissions = {"publish_actions"}
+            facebook.login_with_permissions(permissions, facebook.AUDIENCE_FRIENDS, function(self, data)
+                if (data.status == facebook.STATE_OPEN and data.error == nil) then
+                    print("Successfully logged into Facebook")
+                    pprint(facebook.permissions())
+                else
+                    print("Failed to get permissions (" .. data.status .. ")")
+                    pprint(data)
+                end
+            end)
+            ```
+
+            Log in to Facebook with a set of read permissions
+            ```lua
+            local permissions = {"public_profile", "email", "user_friends"}
+            facebook.login_with_tracking_preference(facebook.LOGIN_TRACKING_LIMITED, permissions, "customcryptononce", function(self, data)
+                if (data.status == facebook.STATE_OPEN and data.error == nil) then
+                    print("Successfully logged into Facebook")
+                    pprint(facebook.permissions())
+                else
+                    print("Failed to get permissions (" .. data.status .. ")")
+                    pprint(data)
+                end
+            end)
+            ```
+
 #*****************************************************************************************************
 
   - name: logout
@@ -83,6 +154,48 @@
 
 #*****************************************************************************************************
 
+  - name: set_default_audience
+    type: function
+    desc: iOS ONLY. The audience that should be able to see the publications. Should be called before `facebook.login_with_tracking_preference()`;
+              Can be any of
+
+                - `facebook.AUDIENCE_NONE`
+
+                - `facebook.AUDIENCE_ONLYME`
+
+                - `facebook.AUDIENCE_FRIENDS`
+
+                - `facebook.AUDIENCE_EVERYONE`
+#*****************************************************************************************************
+
+  - name: get_current_authentication_token
+    type: function
+    desc: iOS ONLY. Get the current AuthenticationToken.
+
+          This function returns the currently stored authentication token after a previous
+          successful login. If it returns nil no access token exists and you need
+          to perform a login to get the wanted permissions.
+
+    returns:
+      - name: authentication_token
+        type: string
+        desc: the authentication token or nil if the user is not logged in
+
+#*****************************************************************************************************
+
+  - name: get_current_profile
+    type: function
+    desc: iOS ONLY. Get the current [FBSDKProfile.currentProfile](https://developers.facebook.com/docs/facebook-login/limited-login/ios/).
+          [Reading From Profile Helper Class](https://developers.facebook.com/docs/facebook-login/limited-login/permissions/profile-helper)
+
+    returns:
+      - name: current_profile
+        type: table
+        desc: After your application receives the logged-in user’s authentication token, you can use
+              this function to read information that user has granted to your application.
+
+#****************************************************************************************************
+
   - name: init
     type: function
     desc: Initialize Facebook SDK (if facebook.autoinit is 0 in game.project)
@@ -648,3 +761,11 @@
   - name: AUDIENCE_EVERYONE
     type: number
     desc: Publish permission to reach everyone
+
+  - name: LOGIN_TRACKING_LIMITED
+    type: number
+    desc: Login tracking Limited
+
+  - name: LOGIN_TRACKING_ENABLED
+    type: number
+    desc: Login tracking enabled
diff --git a/facebook/src/facebook.cpp b/facebook/src/facebook.cpp
@@ -164,20 +164,7 @@ static int Facebook_LoginWithTrackingPreference(lua_State* L)
 
     int login_tracking = luaL_checkinteger(L, 1);
     luaL_checktype(L, 2, LUA_TTABLE);
-    int type = lua_type(L, 3);
-    const char* crypto_nonce = 0x0;
-    if (type == LUA_TSTRING)
-    {
-        crypto_nonce = lua_tostring(L, 3);
-    }
-    else if (type == LUA_TNIL)
-    {
-        // do nothing, it's fine
-    }
-    else
-    {
-        return luaL_error(L, "`crypto_nonce` should be string or `nil`");
-    }
+    const char* crypto_nonce = luaL_checkstring(L, 3);
     dmScript::LuaCallbackInfo* callback = dmScript::CreateCallback(L, 4);
 
     char* permissions[128];

diff --git a/facebook/src/facebook_ios.mm b/facebook/src/facebook_ios.mm
@@ -627,12 +627,6 @@ int Platform_FacebookInit(lua_State* L)
     return 0;
 }
 
-
-void Platform_OnEventFacebook(dmExtension::Params* params, const dmExtension::Event* event)
-{
-    (void)params; (void)event;
-}
-
 void Platform_FacebookSetDefaultAudience(int audience)
 {
     [g_Facebook.m_Login setDefaultAudience: convertDefaultAudience(audience)];