Android Integration of Magnes

Before you begin

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

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)
        .setNotificationToken(String notificationToken)
        .setMagnesNetworkingFactory
           (MagnesNetworkingFactoryImpl magnesNetworkingFactoryImpl)
        .enableNetworkOnCallerThread(boolean networkOnCallerThread)
        .disableRemoteConfig(boolean disableRemoteConfig)
        .build();
MagnesSDK.getInstance().setUp(magnesSettings);

Setup parameters and methods

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.

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.

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.