See our Developer Portal to get started with developing for the Strivacity product.

Overview

This SDK allows you to integrate Strivacity's policy-driven journeys into your brand's Android mobile application using native mobile experiences via Journey-flow API for native clients.

The SDK uses the PKCE extension to OAuth to ensure the secure exchange of authorization codes in public clients.

How to use

Strivacity SDK for Android is available on GitHub releases.

Demo Application

A demo application is available in the demoapplication folder.

Overview

The Strivacity SDK for Android provides the possibility to build an application which can communicate with Strivacity using OAuth 2.0 PKCE flow.

Instantiate and initialize Native SDK

First, in your Activity you must create a NativeSDK instance:

TenantConfiguration tenantConfiguration = new TenantConfiguration(
        Uri.parse("<issuer-url>"),              // specifies authentication server domain, e.g.: https://your-domain.tld
        "<client-id>",                          // specifies OAuth2 client ID
        Uri.parse("<redirect-uri>"),            // specifies the redirect uri, e.g.: android://native-flow
        Uri.parse("<post-logout-uri>")          // specifies the post logout uri, e.g.: android://native-flow
);

NativeSDK nativeSDK =
    NativeSDK
        .builder()
        .tenantConfiguration(tenantConfiguration)
        .viewFactory(new ViewFactory(this))
        .cookieHandler(new CookieManager())
        .sharedPreferences(this.getSharedPreferences("test", MODE_PRIVATE))
        .build();

Register the custom schema

The custom schema used in the redirect and post logout uri's needs to be registered for your application. Create an intent-filter xml tag in your AndroidManifest.xml file in one of your activity tags. Set the same schema and host parameters provided in the TenantConfiguration.

For example:

<activity android:name=".RedirectActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.VIEW" />

       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />

       <data android:host="native-flow" android:scheme="android" />
   </intent-filter>
</activity>

Create an Activity to handle the call from the custom schema and pass the required information back to you primary Activity For example:

public class RedirectActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Intent intent = new Intent(this, MainActivity.class);
        intent.setData(getIntent().getData());
        intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);

        startActivity(intent);
        finish();
    }
}

In your primary Activity provide an implementation for the onResume method and call the continueFlow method on the nativeSDK instance.

 @Override
 protected void onResume() {
     super.onResume();
     if (getIntent().getData() != null) {
         nativeSDK.continueFlow(getIntent().getData());
     }
 }

Network Configuration

The NetworkConfiguration class controls the HTTP layer of the SDK. All properties are optional and fall back to sensible defaults. Use NetworkConfiguration.builder() to construct an instance, or NetworkConfiguration.defaultConfiguration() for the default settings.

NetworkConfiguration networkConfiguration = NetworkConfiguration.builder()
    .userAgent("strivacity-sdk-android")          // Value of the User-Agent header sent with every request
    .customRequestHeaders(Collections.emptyMap()) // Extra headers appended to every request (keys must start with `x-sty-`)
    .build();

userAgent — overrides the User-Agent header value. Useful when you need to identify your app alongside the SDK. Must be at least 3 characters after trimming; an IllegalArgumentException is thrown at construction time otherwise.

customRequestHeaders — additional headers included in every outgoing request. Keys must satisfy all of the following rules:

• prefixed with x-sty- (e.g. x-sty-my-header)
• entirely lowercase
• not equal to the bare prefix "x-sty-" (i.e. must have at least one character after the prefix)

Violating any of these rules throws an IllegalArgumentException at construction time. Headers carrying the x-sty- prefix are forwarded to the Strivacity backend and are accessible inside Hooks, allowing server-side logic to act on values passed from the mobile app (e.g. app version, feature flags).

Adding the SDK version header

The addSdkVersionCustomHeader() method returns a copy of NetworkConfiguration with the x-sty-sdk-version header set to the current SDK version. If the header is already present, the existing instance is returned unchanged. This header is forwarded to server-side Hooks, making it easy to correlate backend events with a specific SDK release.

NetworkConfiguration.defaultConfiguration().addSdkVersionCustomHeader()

Note for SDK developers: The SDK version is sourced from the sdkVersion Gradle property (set via -PsdkVersion=<value> at build time). When the property is not provided — e.g. during local development — the version defaults to 0.0.0.

Example — adding the SDK version and a custom app-version header:

NativeSDK nativeSDK = NativeSDK
    .builder()
    .tenantConfiguration(tenantConfiguration)
    .networkConfiguration(
        NetworkConfiguration.builder()
            .customRequestHeaders(Map.of("x-sty-app-version", "1.2.3"))
            .build()
            .addSdkVersionCustomHeader()
    )
    .build();

How to launch a login flow

Login flow can be launched using the login method on the nativeSDK instance.

void login(
     LoginParameters loginParameters,        // additional parameters to pass through during login
     ViewGroup parentLayout,                 // the parent layout where the login flow should be rendered
     Consumer<IdTokenClaims> onSuccess,      // callback method that will be called after a successful login
     Consumer<Throwable> onError             // callback method that will be called if an error occures
 )

The following additional parameters can be set:

public class LoginParameters {

    private final String prompt;             // sets the corresponding parameter in the OAuth2 authorize call
    private final String loginHint;          // sets the corresponding parameter in the OAuth2 authorize call
    private final List<String> acrValues;    // sets the corresponding parameter in the OAuth2 authorize call
    private final List<String> scopes;       // sets the corresponding parameter in the OAuth2 authorize call

    private String uiLocales = Locale.getDefault().toLanguageTag();  // sets the language of the flow
}

To cancel an on-going flow the cancelFlow method can be used on the nativeSDK instance.

Handling a logged-in session

The getIdTokenClaims method can be used on the nativeSDK instance to check if there is a logged in session already it will return null in case there is none. If there is an existing session the method above will give back the claims.

The access token can be retrieved using the getAccessToken method on the nativeSDK instance.

To validate if the current session's access token is still valid, the isAuthenticated method can be called on the nativeSDK instance. This call will also try to refresh the access token, if a refresh token is available.

To trigger a logout the logout method can be called on the nativeSDK instance.

Author

Strivacity: opensource@strivacity.com

License

Strivacity is available under the Apache License, Version 2.0. See the LICENSE file for more info.

Vulnerability Reporting

The Guidelines for responsible disclosure details the procedure for disclosing security issues. Please do not report security vulnerabilities on the public issue tracker.