Android Integration of Magnes

DocsLast updated: June 20th 2023, @ 1:16:15 pm


Before you begin

The following table lists prerequisite information for integrating Magnes on the Android platform:

PrerequisiteDescription
OS versionUse the latest Android version, if possible.
Software configurationThe central class for Magnes is lib.android.paypal.com.magnessdk.MagnesSDK.
This class provides single access for the host app.

Adding permissions

Before initializing the Magnes library, you must add permissions and metadata settings in the app's manifest file so Magnes can access essential mobile data for risk assessment. Add the following in AndroidManifest.XML:

<manifest>
  <!-- following permissions are optional -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <uses-permission android:name="android.permission.GET_ACCOUNTS" />
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.READ_PHONE_STATE" />
  <!-- for reading GSF ID -->
  <uses-permission
   android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
</manifest>

Setting up Magnes

Magnes must be set up at app startup. The setUp call is executed only once per lifecycle of a Magnes Singleton Instance. The Setup parameters and methods listed below are optional. You can set Magnes to use either simple or advanced setup. Advanced setup gives more customizability and the option to pass in more parameters. Most developers will opt for the simple setup. Use those with which you are familiar, otherwise build a default setup without using any parameters.

Magnes setup simple

MagnesSettings magnesSettings = new MagnesSettings.Builder(context).build();
MagnesSDK.getInstance().setUp(magnesSettings);

Magnes setup advanced

magnesSettings = new MagnesSettings.Builder(@NonNull Context context)
        .setAppGuid(@Size(max = APPGUID_MAXLENGTH) String appGuid)
        .setMagnesEnvironment(Environment.LIVE)
        .setMagnesSource(@MagnesSource.SourceFlow int sourceFlow)
        .setHasUserLocationConsent(boolean hasUserLocationConsent)
        .setNotificationToken(String notificationToken)
        .setMagnesNetworkingFactory
           (MagnesNetworkingFactoryImpl magnesNetworkingFactoryImpl)
        .enableNetworkOnCallerThread(boolean networkOnCallerThread)
        .disableRemoteConfig(boolean disableRemoteConfig)
        .build();
MagnesSDK.getInstance().setUp(magnesSettings);

Setup parameters and methods

Parameter or MethodData TypeDescription
contextContextAndroid application context
setAppGuid()StringSets an application's globally unique identifier, which identifies the merchant application that sets up Magnes on the mobile device. If the merchant app does not pass an AppGuid, Magnes creates one to identify the app. If the app is installed or reinstalled, it receives a new AppGuid. Maximum length: 36 characters.
setMagnesEnvironmentenum EnvironmentSetting the environment for Magnes. Please pass Environment.LIVE , for production release. Environment.SANDBOX for sandbox environment, if a verification has to be done prior to production release
setMagnesSource()IntDefIntegration defined sources: MagnesSource.PAYPAL, MagnesSource.EBAY, and MagnesSource.BRAINTREE. If none of these apply to your integration, either use MagnesSource.DEFAULT or do not set a source.
setHasUserLocationConsent()BooleanToggle to pass the constant for the third-party SDKs to collect location-related information. This parameter is set to false by default. Note: This is different than the Location Permission system dialog shown to the user.
disableRemoteConfig()BooleanToggle to trigger a remote configuration networking call. It triggers once per application lifecycle. The default is false.
enableNetworkOnCallerThread()BooleanEnable a network call on the current caller thread.
Note: It might throw a NetworkOnMainThreadException if your caller thread is the main thread.
setMagnesNetworking
Factory()
MagnesNetworkingFactoryImplMagnes uses this custom networking factory instead of the Magnes default one in order to trigger the networking call. You must implement MagnesNetworking and MagnesNetworkingFactory.

Collect and submit the payload

When the user launches the mobile app, Magnes remains active only while the Setup, Collect, and CollectAndSubmit methods run. It does not passively collect data in the background.

You can turn on the debug log to ensure that Magnes is running successfully.

Magnes generates and returns a new PayPal-Client-Metadata-Id, which is a unique 32-character string. Upon collecting the core and dynamic data, Magnes causes the library to submit an asynchronous payload to PayPal Risk Services.

Ordinarily, Magnes generates the PayPal-Client-Metadata-Id, but you can pass in a value to be used as the ID.

Magnes CollectAndSubmit - simple

MagnesResult magnesResult = MagnesSDK.getInstance()
   .collectAndSubmit(@NonNull Context context)

Magnes CollectAndSubmit - advanced

MagnesResult magnesResult = MagnesSDK.getInstance()
   .collectAndSubmit(Context context, String paypalClientMetaDataId,
     HashMap<String, String>
     additionalData)

The following table lists parameters you can pass in the payload, including additional wanted data as key-value pairs.

ParameterData TypeDescription
contextContextAndroid application context.
PaypalClientMetaDataIDStringYour own unique identifier for the payload. If you do not pass in this value, a new PayPal-Client-Metadata-Id is generated per method call. Maximum length: 32 characters.
additionalDataHashMap<String, String>Any key-value pair in this HashMap is injected into the payload submitted to the PayPal server.

Get the Magnes result

In every data collection call, the Magnes Library returns back to the caller a MagnesResult containing the latest device information and the PayPal-Client-Metadata-Id:

MagnesResult

// cached the MagnesResult from previous collectAndSubmit call.
// MagnesResult magnesResult =
// MagnesSDK.getInstance().collectAndSubmit(@NonNull Context context)
//
String paypalcmid = magnesResult.getPaypalClientMetaDataId()
JSONObject deviceInfo =  magnesResult.getDeviceInfo()

The following table lists methods you can use in a data collection call.

MethodData TypeDescription
getPaypalClientMetaDataId()StringThe newly generated (or passed in) PayPal-Client-Metadata-Id from the latest API call.
getDeviceInfo()JSONObjectA full device information payload. This payload is identical to the payload submitted to the PayPal server.

Send the PayPal-Client-Metadata-ID from the merchant server to PayPal

The PayPal-Client-Metadata-Id pairs the Magnes payload in the context of a PayPal transaction payment, login, or consent, or other PayPal activity.

When the merchant server makes a call to PayPal Payment or other APIs, that payment call must include the most recent PayPal-Client-Metadata-Id that Magnes (or the merchant app) provided. For most REST APIs, you must include in the call header the PayPal-Client-Metadata-Id key with the ID’s most recent value as that key’s value.

For NVP/SOAP or other APIs, refer to the API documentation or integration details provided by your PayPal representative.