Migration guide

Migrating to 7.0.0

Migrating to 7.0.0 consist of two stages

1. Migration Guide from JDK 11 to JDK 17
2. Migration Guide from Android API Level 33 to API Level 35

1. Migration Guide from JDK 11 to JDK 17

Overview

Migrating from JDK 11 to JDK 17 involves updating your project to leverage the latest features, performance improvements, and security enhancements provided by Java 17. This guide will walk you through the necessary steps to ensure a smooth transition.

Steps

1. Download JDK 17

   First, download JDK 17 from Android Studio settings:

   • Go to File -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle.
   • In the Gradle JDK drop-down, select Download JDK and choose JDK 17.


2. Update Project Configuration

   Modify your build configuration to specify Java 17 as the target version. This involves updating the build.gradle file in your project.

   android {
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_17
           targetCompatibility JavaVersion.VERSION_17
       }
       kotlinOptions {
           jvmTarget = "17"
       }
   }

   In your project-level build.gradle file, if you are using Kotlin, update the Kotlin version to 1.8.21 (or the latest available)

   buildscript {
       ext.kotlin_version = "1.8.21"
   }

   Update Android Gradle Plugin (AGP), in project-level build.gradle file, update the android build gradle dependency to:

   dependencies {
       classpath "com.android.tools.build:gradle:8.8.2"
   }

   In the gradle-wrapper.properties file, update the distributionUrl to:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip

3. Update Dependencies

   Ensure all dependencies are compatible with Java 17. Check for updates or replacements for any libraries that may not support Java 17.

4. Testing

   Thoroughly test your application to identify and resolve any issues that may arise from the migration. Use automated tests to ensure compatibility and stability.

5. Build and Deployment

   Update your build tools and CI/CD pipelines to use Java 17. Deploy the updated application to a staging environment for further testing before production rollout.

Benefits

• Improved performance and security.
• Access to new language features.
• Enhanced stability and efficiency.

2. Migration Guide from Android API Level 33 to API Level 35

Overview

Migrating from Android API Level 33 to API Level 35 involves updating your project to target the latest Android platform, ensuring compatibility with new features and optimizations.

Note: If you are targeting your application to Android API 35, it is mandatory to upgrade to Java 17. Google recommends using Java 17 as the minimum JDK version for targeting Android API 35. For more details, you can refer to the official documentation here.

Steps

1. Update Project Configuration

   Modify your build.gradle file to set compileSdkVersion and targetSdkVersion to 35:

   android {
   namespace("com.example.appname") // you need to add your package name here
       compileSdkVersion 35
       defaultConfig {
           targetSdkVersion 35
       }
   }

2. Update Dependencies

   Update all android and androidTest dependencies to their latest stable versions. Update the Kotlin version to 1.8.21 (or the latest available).

3. Edge-to-Edge Design Principles

   Implement edge-to-edge design principles to fully utilize the screen area. Refer to the Edge-to-Edge Design Guidelines for detailed instructions.

4. Testing            

   Test your application with the updated configurations in a staging environment to ensure compatibility and identify any potential issues early.

   Testing should include:

   • Staging Environment: Test your application with the updated configurations in a staging environment to ensure compatibility and identify any potential issues early.
                  
   • Device Coverage: Test on multiple devices ranging from the minimum API level supported by your application to API level 35. This ensures that your application works seamlessly across different Android versions and devices.
                  
   • Functional Testing: Verify that all functionalities of your application work as expected with the new configurations.
                  
   • Performance Testing: Assess the performance improvements brought by the new Android API level.
                  
   • Regression Testing: Ensure that existing features continue to work correctly after the migration.
              
          

Increased the minimal required API level

In order to support the new features and payment methods the minimal API level required for Mobile SDK has been changed to 24.

Please make sure your application uses minSdkVersion 24 or above.

Handling asynchronous payments with Ready-to-Use UI

To simplify the Ready-to-Use UI integration the CheckoutActivity will handle the redirect to the shopper result URL. For this reason the shopper result URL has been removed from the CheckoutSettings. As a result setting the intent filter for the shopper result URL and handling the redirect in onNewIntent callback are not required anymore.

API Deprecations

	Deprecated in 5.x.x	Use instead in 6.x.x
CheckoutThreeDS2Flow		Not used anymore.
CheckoutInfo
	String[] getThreeDS2Brands()	Not used anymore.
	CheckoutThreeDS2Flow getThreeDS2Flow()	Not used anymore.
	boolean isBrowserParamsRequired()	Not used anymore.

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
checkoutSettings.threeDSConfig = config;

let config = OPPThreeDSConfig()
checkoutSettings.threeDSConfig = config

Required dependencies

Because Mobile SDK distributed as .aar file it doesn't include transitive dependencies. Your application build.gradle must define them.

implementation "androidx.appcompat:appcompat:1.4.2"
implementation "androidx.recyclerview:recyclerview:1.2.1"
implementation "androidx.browser:browser:1.4.0"
implementation "androidx.fragment:fragment-ktx:1.4.1"
implementation "androidx.constraintlayout:constraintlayout:2.1.4"
implementation "androidx.webkit:webkit:1.6.0"
implementation "com.google.android.material:material:1.6.1"
implementation "com.google.code.gson:gson:2.8.9"

Make sure viewBinding feature is enabled.

buildFeatures {
    viewBinding true
}

Simplified 3D Secure 2.x integration

Since Mobile SDK 5.0.0 the external initialization of 3DS service was removed. Now it is fully managed by Mobile SDK. Please check 3D Secure 2 page for more details.

Using Activity Result API

The Mobile SDK started to use Activity Result API for Ready-to-Use UI. The method to create the intent was removed from CheckoutSettings, use CheckoutActivityResultContract instead. Please check Present Checkout UI for more details.

API Deprecations

	Deprecated in 4.x.x	Use instead in 5.x.x
CheckoutSettings
	Intent createCheckoutActivityIntent(Context context)	CheckoutActivityResultContract
	CheckoutSettings setProviderDomain(Connect.ProviderDomain providerDomain)	Not used anymore.
	Intent createCheckoutActivityIntent(Context context, ComponentName componentName)	CheckoutActivityResultContract
PaymentButtonFragment
	void submitTransaction(CheckoutSettings checkoutSettings, ComponentName componentName)	Set componentName in the CheckoutSettings before submitting transaction.
CardPaymentParams
	boolean isNumberValid(String cardNumber)	boolean isNumberValid(String cardNumber, boolean luhnCheck)
	boolean checkLuhn(String cardNumber)	boolean isNumberValid(String cardNumber, boolean luhnCheck)
OppPaymentProvider
	OppPaymentProvider(Context context, Connect.ProviderMode providerMode, Connect.ProviderDomain providerDomain)	Not used anymore.
	void requestPaymentBrandsForBin(String bin, String checkoutId, ITransactionListener listener)	void requestBinInfo(String checkoutId, String bin, BinInfoListener listener
	void sendThreeDS2AuthParams(String authParams, Transaction transaction, ThreeDS2AuthResponseListener listener)	The authentication parameters will be sent automatically.

Naming changes

com.oppwa.mobile.connect.threeds.OppThreeDSConfig -> com.oppwa.mobile.connect.provider.threeds.v2.model.ThreeDSConfig
com.oppwa.mobile.connect.threeds.constant.ChallengeUiType -> com.oppwa.mobile.connect.provider.threeds.v2.model.ChallengeUiType

ipworks3ds_sdk.xcframework // certified 3DS SDK

One framework instead of two

Mobile 3DS SDK wrapper oppwa.mobile.threeds.aar is deprecated now - all 3DS functionality is build into Mobile SDK oppwa.mobile.aar. So before moving forward remove oppwa.mobile.threeds.aar from your project.

Import mandatory library

As 3DS SDK now is a part of Mobile SDK you have to import the following framework to the project:

ipworks3ds_sdk.aar // certified 3DS SDK

Drag and drop ipworks3ds_sdk.aar (use ipworks3ds_sdk_deploy.aar for production) to the "libs" folder of the module where you plan to integrate Mobile SDK.

There are two versions of the ipworks3ds_sdk included: one to be used for development and one for production. The production version includes more strict security measures that would not allow for common development processes to occur, including running with attached debuggers or using simulators/emulators. The deployment version includes _deploy in the filename.