Xamarin doc update #78

get-started/authentication-approach/token-based.md

@@ -46,6 +46,10 @@ Choose your platform below:
 
 {% page-ref page="../ios.md" %}
 
+{% page-ref page="../flutter.md" %}
+
+{% page-ref page="../xamarin.md" %}
+
 ### 2. Backend Integration
 
 {% page-ref page="../backend-integration/" %}

get-started/xamarin.md

@@ -265,6 +265,30 @@ namespace MyApp
 }
 ```
 
+## Get the Logged In State
+
+The `SessionState` reflects the user logged in state in the SDK locally on the device. That means even the `SessionState` is `Authenticated`, the session may be invalid if it is revoked remotely. After initializing the Authgear SDK, call `FetchUserInfoAsync` to update the `SessionState` as soon as it is proper to do so.
+
+```csharp
+// value can be NoSession or Authenticated
+// After Authgear.ConfigureAsync, it only reflects local state.
+var sessionState = authgear.SessionState;
+
+if (sessionState == SessionState.Authenticated)
+{
+    try
+    {
+        var userInfo = await authgear.FetchUserInfoAsync();
+        // sessionState is now up to date
+    }
+    catch (Exception ex)
+    {
+        // sessionState is now up to date
+        // it will change to NoSession if the session is invalid
+    }
+}
+```
+
 ## Logout
 
 To log out the user from the current app session, you need to invoke the`logout`function.
@@ -273,6 +297,25 @@ To log out the user from the current app session, you need to invoke the`logout`
 await authgear.LogoutAsync();
 ```
 
+## Calling An API
+
+To include the access token to the HTTP requests to your application server, you set the bearer token manually by using `authgear.AccessToken`.
+
+### Using HttpClient
+
+You can get the access token through `authgear.AccessToken`. Call `RefreshAccessTokenIfNeededAsync` every time before using the access token, the function will check and make the network call only if the access token has expired. Then, include the access token into the Authorization header of the http request.
+
+```csharp
+await authgear.RefreshAccessTokenIfNeededAsync();
+// Access token is ready to use
+// AccessToken can be string or undefined
+// It will be empty if user is not logged in or session is invalid
+var accessToken = authgear.AccessToken;
+var client = GetHttpClient();  // Get the re-used http client of your app, as per recommendation.
+var httpRequestMessage = new HttpRequestMessage(myHttpMethod, myUrl);
+httpRequestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
+```
+
 ## Next steps
 
 To protect your application server from unauthorized access. You will need to **integrate your backend with Authgear**.

integrate/account-deletion.md

@@ -39,6 +39,15 @@ await authgear.getUserInfo();
 ```
 {% endtab %}
 
+{% tab title="Xamarin" %}
+```csharp
+// This method blocks until the user closes User Settings.
+await authgear.OpenAsync(SettingsPage.Settings);
+// One way to verify the validity of the session is to get User Info once.
+await authgear.FetchUserInfoAsync();
+```
+{% endtab %}
+
 {% endtabs %}
 
 ## Deactivated User

integrate/auth-ui.md

@@ -68,6 +68,15 @@ Future<void> onPressOpenSettingsPage() async {
 ```
 {% endtab %}
 
+{% tab title="Xamarin" %}
+```csharp
+async void OnOpenSettingsClicked(object sender, EventArgs args)
+{
+  await authgear.OpenAsync(SettingsPage.Settings);
+}
+```
+{% endtab %}
+
 {% tab title="iOS" %}
 ```swift
 func onPressOpenSettingsPage(sender: UIButton, forEvent event: UIEvent) {

integrate/force-authentication-on-app-launch.md

@@ -29,6 +29,24 @@ final authgear = Authgear(
 ```
 {% endtab %}
 
+{% tab title="Xamarin" %}
+```csharp
+var authgearOptions = new AuthgearOptions
+{
+    ClientId = CLIENT_ID,
+    AuthgearEndpoint = ENDPOINT,
+    TokenStorage: new TransientTokenStorage(),
+};
+#if __ANDROID__
+var authgear = new AuthgearSdk(GetActivity().ApplicationContext, authgearOptions);
+#else
+#if __IOS__
+var authgear = new AuthgearSdk(UIKit.UIApplication.SharedApplication, authgearOptions);
+#endif
+#endif
+```
+{% endtab %}
+
 {% tab title="iOS" %}
 ```swift
 Authgear(

integrate/reauthentication.md

@@ -130,6 +130,65 @@ Future<void> onClickPerformSensitiveOperation() async {
 ```
 {% endtab %}
 
+{% tab title="Xamarin" %}
+```csharp
+var ios = new BiometricOptionsIos
+{
+    LocalizedReason = "Use biometric to authenticate",
+    AccessConstraint = BiometricAccessConstraintIos.BiometricAny,
+};
+var android = new BiometricOptionsAndroid
+{
+    Title = "Biometric Authentication",
+    Subtitle = "Biometric authentication",
+    Description = "Use biometric to authenticate",
+    NegativeButtonText = "Cancel",
+    AccessConstraint = BiometricAccessConstraintAndroid.BiometricOnly,
+    InvalidatedByBiometricEnrollment = false,
+};
+
+async void OnPerformSensitiveOperationClicked(object sender, EventArgs args)
+{
+    // Step 1: Refresh the ID token to ensure the claims are up-to-date.
+    await authgear.RefreshIdTokenAsync();
+
+    // Step 2: Check if the end-user can be reauthenticated.
+    var canReauthenticate = authgear.CanReauthenticate;
+    if (!canReauthenticate)
+    {
+        // Step 2.1: Depending on your business need, you may want to allow
+        // the end-user to proceed.
+        // Here we assume you want to proceed.
+        var idTokenHint = authgear.IdTokenHint;
+
+        // Step 2.2: Call the sensitive endpoint with the ID token.
+        // It is still required to pass the ID token to the endpoint so that
+        // the endpoint can know the end-user CANNOT be reauthenticated.
+        await CallMySensitiveEndpointAsync(idTokenHint);
+        return;
+    }
+
+    // Step 3: The end-user can be reauthenticated.
+    // If your app supports biometric authentication, you can pass
+    // the biometric options to reauthenticate.
+    // If biometric is enabled for the current user, it will be used instead.
+    await authgear.ReauthenticateAsync(new ReauthenticateOptions
+    {
+        RedirectURI: THE_REDIRECT_URI,
+    }, new BiometricOptions
+    {
+        Ios = ios,
+        Android = android,
+    });
+
+    // Step 4: If we reach here, the reauthentication was done.
+    // The ID token have up-to-date auth_time claim.
+    var idTokenHint = authgear.IdTokenHint;
+    await CallMySensitiveEndpointAsync(idTokenHint);
+}
+```
+{% endtab %}
+
 {% tab title="Web" %}
 ```typescript
 async function onClickPerformSensitiveOperation() {
@@ -358,6 +417,28 @@ public void onClickPerformSensitiveOperation() {
 }
 ```
 {% endtab %}
+
+{% tab title="Xamarin" %}
+```csharp
+public async void OnPerformSensitiveOperationClicked(object sender, EventArgs args)
+{
+    await authgear.RefreshIdTokenAsync();
+    var authTime = authgear.AuthTime;
+    if (authTime != null)
+    {
+        var now = DateTimeOffset.UtcNow;
+        var timedelta = now - authTime.Value;
+        if (timedelta < TimeSpan.FromMinutes(5))
+        {
+            var idTokenHint = authgear.IdTokenHint;
+            callMySensitiveEndpoint(idTokenHint);
+            return;
+        }
+    }
+}
+```
+{% endtab %}
+
 {% endtabs %}
 
 ## Backend Integration

integrate/single-sign-on.md

@@ -34,6 +34,25 @@ final authgear = Authgear(
 ```
 {% endtab %}
 
+{% tab title="Xamarin" %}
+```csharp
+var authgearOptions = new AuthgearOptions
+{
+    ClientId = CLIENT_ID,
+    AuthgearEndpoint = ENDPOINT,
+    ShareSessionWithSystemBrowser = true,
+};
+// Android
+#if __ANDROID__
+var authgear = new AuthgearSdk(GetActivity().ApplicationContext, authgearOptions);
+#else
+#if __IOS__
+var authgear = new AuthgearSdk(UIKit.UIApplication.SharedApplication, authgearOptions);
+#endif
+#endif
+```
+{% endtab %}
+
 {% tab title="iOS" %}
 ```swift
 Authgear(

integrate/user-profile.md

@@ -60,6 +60,21 @@ authgear.fetchUserInfo(new OnFetchUserInfoListener() {
 });
 ```
 {% endtab %}
+
+{% tab title="Xamarin" %}
+```csharp
+try
+{
+    var userInfo = await authgear.FetchUserInfoAsync()
+}
+catch
+{
+    // failed to fetch user info
+    // the refresh token maybe expired or revoked
+}
+```
+{% endtab %}
+
 {% endtabs %}
 
 ## Standard Attributes