iOS Swift SDK Integration

Docs

Last updated: Aug 15th, 7:33am

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:

PrerequisiteDescription
OS versionUsing the latest iOS version is recommended.
Software configurationYou can use the Magnes iOS Swift library for apps written in the Swift language.
MagnesSDKMagnesSDK is the central class for the Swift library. It provides singleton access for the host app.

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

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

    Magnes setup Swift App to Swift SDK – advanced

      1//@objc public func setUp(setOptionalAppGuid appGuid: String = "",
      2// disableRemoteConfiguration isDisabled: Bool = false,
      3// magnesSource source: MagnesSource =
      4// MagnesSource.DEFAULT)
      5
      6
      7MagnesSDK magnesSDK = MagnesSDK.shared()
      8magnesSDK.setUp(setOptionalAppGuid: "YOUR-APPGUID",
      9 setOptionalAPNToken:"YOUR-APP-NOTIFICATION-TOKEN",
      10 disableRemoteConfiguration: false,
      11 magnesSource: MagnesSource)

      Magnes setup Objective-C App to Swift MagnesSDK

      Import the exposed classes from library using the following statement:

        1#import <PPRiskMagnes/PPRiskMagnes-Swift.h>
          1//@objc public func setUp(setEnviroment env: Environment = Environment.LIVE,
          2// setOptionalAppGuid appGuid: String = "",
          3// setOptionalAPNToken apnToken: String = "",
          4// disableRemoteConfiguration isRemoteConfigDisabled:
          5// Bool = false,
          6// disableBeacon isBeaconDisabled: Bool = false,
          7// magnesSource source: MagnesSource =
          8// MagnesSource.DEFAULT)
          9
          10MagnesSDK *magnessdk = [MagnesSDK shared];
          11[magnesSDK setUpWithSetEnviroment:EnvironmentLIVE
          12 setOptionalAppGuid:@"YOUR-APPGUID"
          13 setOptionalAPNToken:@"YOUR-APNS-TOKEN"
          14 disableRemoteConfiguration:false
          15 disableBeacon:false
          16 magnesSource:MagnesSourceDEFAULT];

          Setup parameters and methods

          Parameter NameData TypeDescription
          setEnviromentEnvironmentSetting the environment for Magnes. Please pass MagnesSDK.Environment.LIVE for production release. Environment.SANDBOX ,if we need to verify prior to production release
          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.
          SetOptionalAPNTokenStringUse an Apple Push Notification Service (APNS) token to send notifications to the mobile device.
          DisableRemoteConfigurationBooleanEnables the consumer app to receive the latest Magnes configuration settings. The default is false.
          MagnesSourceMagnesSourceIntegration 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.

          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

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

            Swift App to Swift SDK: Collect data – advanced

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

              Objective C App to Swift Library: Collect data – simple

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

                Objective C App to Swift Library: Collect data – advanced

                  1MagnesResult *magnesResult = [[MagnesSDK shared]
                  2collectWithPayPalClientMetadataId:"YOUR-PAYPAL-CLIENT-METADATA-ID"
                  3withAdditionalData: (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

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

                    Swift App to Swift SDK: Collect and submit – advanced

                      1// @objc public func collect(withPayPalClientMetadataId cmid: String,
                      2// withAdditionalData additionalData: [String: String])
                      3// -> MagnesResult
                      4
                      5let magnesResult:MagnesResult =
                      6MagnesSDK.shared().collectAndSubmit(withPayPalClientMetadataId:
                      7 "YOUR-PAYPAL-CLIENT-METADATA-ID", withAdditionalData: [String: String])

                      From Objective C App to Swift SDK – simple

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

                        From Objective C App to Swift SDK – advanced

                          1Collect and Submit: Advanced
                          2//@objc public func collectAndSubmit(withPayPalClientMetadataId cmid: String,
                          3// withAdditionalData additionalData: [String: String])
                          4// -> MagnesResult
                          5//
                          6
                          7MagnesResult *magnesResult = [[MagnesSDK shared]
                          8collectAndSubmitWithPayPalClientMetadataId:(NSString *)
                          9withAdditionalData:(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.

                          ParameterData TypeDescription
                          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.
                          withAdditionalData[String:String]Any key-value pair in NSDictionary 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:

                          Get the MagnesResult from Swift app to Swift SDK

                            1// cached the MagnesResult from previous collectAndSubmit call.
                            2
                            3let magnesResult:MagnesResult = MagnesSDK.shared().collectAndSubmit()
                            4
                            5let paypalcmid:String = magnesResult.getPayPalClientMetaDataId()
                            6var magnesPayload: [String: Any] = 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()NSDictionaryA full device information payload. This payload is identical to the payload submitted to the PayPal server.

                            Get the MagnesResult from from Objective C app to Swift library

                              1// cached the MagnesResult from previous collectAndSubmit call.
                              2// MagnesResult *magnesResult = [[MagnesSDK shared] collectAndSubmit];
                              3
                              4NSString* cmid = [magnesResult getPayPalClientMetaDataId];
                              5NSDictionary* payloadDict = [magnesResult getDeviceInfo];
                              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 other APIs, refer to the API documentation or integration details provided by your PayPal representative.

                              We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies