iOS Swift SDK Integration

This page explains how to integrate the Magnes library on the iOS platform for Swift 4.2.

Before you begin

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

Designate frameworks

Before you initialize Magnes, you must set several frameworks as required so Magnes can access essential mobile data for risk assessment. For example, by setting CoreLocation.framework as required, Magnes can access the current location of the mobile device. This is not mandatory from Xcode 14.

Set the following frameworks as required.

• Security.framework
• CFNetwork.framework
• SystemConfiguration.framework
• MessageUI.framework
• CoreLocation.framework
• Foundation.framework
• CommonCrypto.framework
• UIKit.framework

For more information about setting up frameworks as required, visit https://developer.apple.com.

Import PPRiskMagnes.framework

You must add the library to the application for accessing the APIs in the app. The library is contained in an added framework. To import the Swift library, link PPRiskMagnes.framework to the app, go to Build Phases and select Link Binaries with Libraries.

Set up Magnes for Swift

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 below are optional. You can set up with empty string values. Use parameters with which you are familiar, otherwise build a default setup without using any parameters.

The SetUp call either passes the merchant app’s app_guid, or Magnes creates an app_guid to identify the app. An app_guid is a unique installation identifier of the app for a particular mobile device. If the app is reinstalled, a new app_guid is generated.

Magnes setup Swift App to Swift SDK – simple

MagnesSDK magnesSDK = MagnesSDK.shared()
magnesSDK.setup()

Magnes setup Swift App to Swift SDK – advanced

//@objc public func setUp(setOptionalAppGuid appGuid: String = "",
//                      disableRemoteConfiguration isDisabled: Bool = false,
//                      magnesSource source: MagnesSource =
//                      MagnesSource.DEFAULT)


MagnesSDK magnesSDK = MagnesSDK.shared()
magnesSDK.setUp(setOptionalAppGuid: "YOUR-APPGUID",
                setOptionalAPNToken:"YOUR-APP-NOTIFICATION-TOKEN",
                disableRemoteConfiguration: false,
                magnesSource: MagnesSource)

Magnes setup Objective-C App to Swift MagnesSDK

Import the exposed classes from library using the following statement:

#import <PPRiskMagnes/PPRiskMagnes-Swift.h>  

//@objc public func setUp(setEnviroment env: Environment = Environment.LIVE,
//                            setOptionalAppGuid appGuid: String = "",
//                            setOptionalAPNToken apnToken: String = "",
//                            disableRemoteConfiguration isRemoteConfigDisabled:
//                            Bool = false,
//                            disableBeacon isBeaconDisabled: Bool = false,
//                            magnesSource source: MagnesSource =
//                            MagnesSource.DEFAULT)

MagnesSDK *magnessdk =  [MagnesSDK shared];
[magnesSDK setUpWithSetEnviroment:EnvironmentLIVE
                    setOptionalAppGuid:@"YOUR-APPGUID"
                    setOptionalAPNToken:@"YOUR-APNS-TOKEN"
                    disableRemoteConfiguration:false
                    disableBeacon:false
                    magnesSource:MagnesSourceDEFAULT];

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 are called. 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.

Collect data

Execute the following code snippet in order to trigger the library to collect the payload data.

Swift App to Swift SDK: Collect data – simple

let magnesResult:MagnesResult = MagnesSDK.shared().collect()

Swift App to Swift SDK: Collect data – advanced

let magnesResult:MagnesResult = MagnesSDK.shared().collect(cmid: String,
  additionalData: [String: String])

Objective C App to Swift Library: Collect data – simple

MagnesResult *magnesResult = [[MagnesSDK shared] collect];

Objective C App to Swift Library: Collect data – advanced

MagnesResult *magnesResult = [[MagnesSDK shared]
collectWithPayPalClientMetadataId:"YOUR-PAYPAL-CLIENT-METADATA-ID"
withAdditionalData: (NSDictionary<NSString *,NSString *>)];

Collect and submit data

Execute the following code snippets in order to trigger the library to collect the payload data and send it to the PayPal server.

Swift App to Swift SDK: Collect and submit – simple

let magnesResult:MagnesResult = MagnesSDK.shared().collectAndSubmit()

Swift App to Swift SDK: Collect and submit – advanced

// @objc public func collect(withPayPalClientMetadataId cmid: String,
//                          withAdditionalData additionalData: [String: String])
//                          -> MagnesResult

let magnesResult:MagnesResult =
MagnesSDK.shared().collectAndSubmit(withPayPalClientMetadataId:
  "YOUR-PAYPAL-CLIENT-METADATA-ID", withAdditionalData: [String: String])

From Objective C App to Swift SDK – simple

MagnesResult *magnesResult =  [[MagnesSDK shared] collectAndSubmit];

From Objective C App to Swift SDK – advanced

Collect and Submit: Advanced
//@objc public func collectAndSubmit(withPayPalClientMetadataId cmid: String,
//                          withAdditionalData additionalData: [String: String])
//                             -> MagnesResult
//

MagnesResult *magnesResult =  [[MagnesSDK shared]
collectAndSubmitWithPayPalClientMetadataId:(NSString *)
withAdditionalData:(NSDictionary<NSString *,NSString *>)];

Submit additional data

The merchant can include any additional wanted key-value pair data in the Magnes payload. To pass additional data as a dictionary of key-value pairs, execute the above code snippet with the following parameters.

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:

Get the MagnesResult from Swift app to Swift SDK

// cached the MagnesResult from previous collectAndSubmit call.

let magnesResult:MagnesResult = MagnesSDK.shared().collectAndSubmit()

let paypalcmid:String = magnesResult.getPayPalClientMetaDataId()
var magnesPayload: [String: Any] =  magnesResult.getDeviceInfo()

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

Get the MagnesResult from from Objective C app to Swift library

// cached the MagnesResult from previous collectAndSubmit call.
// MagnesResult *magnesResult =  [[MagnesSDK shared] collectAndSubmit];

NSString* cmid = [magnesResult getPayPalClientMetaDataId];
NSDictionary* payloadDict = [magnesResult getDeviceInfo];

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 other APIs, refer to the API documentation or integration details provided by your PayPal representative.