Skip to content

general

Jump to bottom
YYBartT edited this page May 15, 2023 · 2 revisions

General

This is a reference guide to all the functions used by the Apple Sign In Extension, along with any constants that they may use or return and examples of code that use them. Some of the examples are Extended Examples that also show code from callbacks in the Social Async Event.

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.

Constants

This module includes a set of predefined constants that can be utilized for various purposes. Browse through the available constants to find values relevant to your needs and enhance the efficiency of your code.


Back To Top

AppleSignIn_CrossPlatform_AddScope

This function adds a scope for the sign in request to request additional pieces of user data.

The additional data you can request are for an email address and the user's full name. These are requested using the applesignin_scope or mac_applesignin_scope constants.


Syntax:

AppleSignIn_CrossPlatform_AddScope(scope)
Argument Type Description
scope applesignin_scope or mac_applesignin_scope One of the scope constants

Returns:

N/A


Example:

The following code example would go in the Step Event of a button object to check for a user wanting to sign in using the Apple Sign In API:

if mouse_check_button_pressed(mb_left)
{
    if instance_position(mouse_x, mouse_y, id)
    {
        AppleSignIn_CrossPlatform_AddScope(applesignin_scope_fullname);
        AppleSignIn_CrossPlatform_AddScope(applesignin_scope_email);
        AppleSignIn_CrossPlatform_AuthoriseUser();
    }
}


Back To Top

AppleSignIn_CrossPlatform_ClearScopes

This function clears the scope(s) set for the user when requesting Sign In authorisation.

In general this is not required at any time, but may be useful if you wish to – for example – have a sign in with email and full name permissions. The user may cancel this as they don't want to share that data, so you can clear the permissions using this function and then let them sign in again with only basic permission scopes.


Syntax:

AppleSignIn_CrossPlatform_ClearScopes()

Returns:

N/A


Example:

The code below shows an example of the Social Async Event after the user has pressed a button to sign in to your app and the function AppleSignIn_CrossPlatform_AuthoriseUser has been called:

var _event_id = async_load[? "id"];
switch (_event_id)
{
    case applesignin_signin_response:
    case mac_applesignin_signin_response:
        global.appleSignInState = -1;
        var _json = async_load[? "response_json"];
        if _json != ""
        {
            var _map = json_decode(_json);
            if _map[? "success"] == true
            {
                show_debug_message("Apple Sign In Succeeded");
                global.appleSignInState = applesignin_state_authorized;
            }
            ds_map_destroy(_map);
        }
        if global.appleSignInState == -1
        {
            AppleSignIn_CrossPlatform_ClearScopes();
        }
        break;
}


Back To Top

AppleSignIn_CrossPlatform_AuthoriseUser

This function authorises a user using the Apple Sign In API and their Apple ID credentials.

The async_load map will contain the key "response_json", which can then be decoded into another DS map using the function json_decode or into a struct using json_parse.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

AppleSignIn_CrossPlatform_AuthoriseUser()

Returns:

N/A


Triggers:

Social Async Event

The following keys are always present:

Key Type Description
success Boolean This contains whether authorisation was granted or not. If this is false, none of the other keys listed will be present.
identityToken String This holds the unique identity token string for the session.
userIdentifier String This holds the unique user identifier string.
realUserStatus applesignin_realuserstatus or mac_applesignin_realuserstatus This holds the real user status of the user.
authCode String This holds the unique authorisation code string.

If you have used the AppleSignIn_CrossPlatform_AddScope function before calling the authorise function, then you may have the following additional keys – first, for the applesignin_scope_email / mac_applesignin_scope_email scope:

Key Type Description
email String This will be the user's email address

For the applesignin_scope_fullname / mac_applesignin_scope_fullname scope (note that all of these contain an empty string "" if not available):

Key Type Description
namePrefix String The user's name prefix
phoneticRepresentation String A phonetic representation of the name
givenName String The first name of the user
middleName String The middle name of the user
nameSuffix String Any suffix that may be applicable to the name
nickname String The user's nickname
familyName String The user's family (second) name

Example:

The authorise function would normally be called from a button or a controller object in your game, and would generate an Social Async Event that can be dealt with in the following way:

var _event_id = async_load[? "id"];
switch (_event_id)
{
    case applesignin_signin_response:
    case mac_applesignin_signin_response:
        global.appleSignInState = -1;
        var _json = async_load[? "response_json"];
        if _json != ""
        {
            var _map = json_decode(_json);
            if _map[? "success"] == true
            {
                show_debug_message("Apple Sign In Succeeded");
                global.appleSignInState = applesignin_state_authorized;
            }
            ds_map_destroy(_map);
        }
        break;
}

A global variable stores the sign in state for future reference, where -1 means not signed in / no action has been taken. You can use one of the applesignin_state or mac_applesignin_state extension constants to check for other states as required.



Back To Top

AppleSignIn_CrossPlatform_GetCredentialState

This function retrieves the credential sign in state for your game.

You supply the identity token string for the session (returned as part of the callback when you use the function AppleSignIn_CrossPlatform_AuthoriseUser and the function will trigger an Social Async Event where the {var.async_load} DS map "id" key will be applesignin_credential_response or mac_applesignin_credential_response.

The async_load map will then have a further key "response_json", which will hold a JSON string which can be parsed into a DS map using the function json_decode. This map will have the key "status", which will be one of the applesignin_state or mac_applesignin_state constants.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

AppleSignIn_CrossPlatform_GetCredentialState(token)
Argument Type Description
token String The session identity token

Returns:

N/A


Triggers:

Social Async Event

The event of applesignin_credential_response. It contains the following:

Key Type Description
status applesignin_state or mac_applesignin_state The authorisation status of the user

Example:

The following code shows an example of how the callback response for this function would be parsed in the Social Async Event:

var _event_id = async_load[? "id"];
switch (_event_id)
{
    case applesignin_credential_response:
    case mac_applesignin_credential_response:
        global.appleSignInState = -1;
        var _json = async_load[? "response_json"];
        if _json != ""
        {
            var _map = json_decode(_json);
            global.appleSignInState = _map[? "state"];
            ds_map_destroy(_map);
        }
        break;
}


Back To Top

Mac_AppleSignIn_RegisterWindow

This macOS only function must be used before calling any other function to register the game window for authorisation UI overlays.

ℹ️ NOTE

You don't need to call this yourself if you use the _CrossPlatform versions of the functions. The function AppleSignIn_CrossPlatform_AuthoriseUser calls this function on iOS and tvOS.


Syntax:

Mac_AppleSignIn_RegisterWindow()

Returns:

N/A


Example:

The following code example would go in the Step Event of a button object to check for a user wanting to sign in using the Apple Sign In API:

Mac_AppleSignIn_RegisterWindow();
Mac_AppleSignIn_AuthoriseUser();


Back To Top

applesignin_scope

These constants specify the scope.

These constants are referenced by the following functions:


Member Description
applesignin_scope_fullname Requests the user's full name.
applesignin_scope_email Requests the user's e-mail address.

Back To Top

applesignin_response

These constants specify the type of response.


Member Description
applesignin_signin_response Requests the user's full name.
applesignin_credential_response Requests the user's e-mail address.

Back To Top

applesignin_realuserstatus

These constants specify a user status.

These constants are referenced by the following functions:


Member Description
applesignin_realuserstatus_likelyreal The user is likely a real person.
applesignin_realuserstatus_unknown The system hasn't determined whether the user might be a real person.
applesignin_realuserstatus_unsupported This indicates that the IAP product ID has already been added to the internal product list.

Back To Top

applesignin_state

These constants specify the user's authorisation state.

These constants are referenced by the following functions:


Member Description
applesignin_state_authorized The user has been authorised and has a valid session.
applesignin_state_revoked The user's credentials have been revoked and the session terminated.
applesignin_state_not_found The user doesn't appear to have a session with your app.

Back To Top

mac_applesignin_scope

These constants specify the scope.

These constants are referenced by the following functions:


Member Description
mac_applesignin_scope_fullname Requests the user's full name.
mac_applesignin_scope_email Requests the user's e-mail address.

Back To Top

mac_applesignin_response

These constants specify the type of response.


Member Description
mac_applesignin_signin_response Requests the user's full name.
mac_applesignin_credential_response Requests the user's e-mail address.

Back To Top

mac_applesignin_realuserstatus

These constants specify a user status.

These constants are referenced by the following functions:


Member Description
mac_applesignin_realuserstatus_likelyreal The user is likely a real person.
mac_applesignin_realuserstatus_unknown The system hasn't determined whether the user might be a real person.
mac_applesignin_realuserstatus_unsupported This indicates that the IAP product ID has already been added to the internal product list.

Back To Top

mac_applesignin_state

These constants specify the user's authorisation state.

These constants are referenced by the following functions:


Member Description
mac_applesignin_state_authorized The user has been authorised and has a valid session.
mac_applesignin_state_revoked The user's credentials have been revoked and the session terminated.
mac_applesignin_state_not_found The user doesn't appear to have a session with your app.

GameMaker 2023

Clone this wiki locally