Profiler - iOS

Setting up your Artifactory account

Once you sign the fraud prevention contract with Mangopay, your assigned solutions engineer assesses the integration of your application.

If mobile integration is needed, you will be asked to provide the email addresses of your mobile developers. Once provided, JFrog accounts will be generated for your developers and they will receive an email to set up their account.

Getting started

Installation using Swift Package Manager

1. Create the Dependencies directory inside your project.

$
mkdir Dependencies

2. Set it as your working directory.

$
cd Dependencies

3. Initialize Swift package.

$
swift package init

4. Remove unnecessary test files.

$
rm -r Tests

5. Set up the repository and add your credentials to your .netrc file.

1. Go to the Nethone Artifactory Repository.
2. Find nethonesdk-ios-mangopay-spm repository.
3. In the top right corner, click the Set Me Up button

6. Set Artifactory as a Swift repository.

$
swift package-registry set "https://nethone.jfrog.io/artifactory/api/swift/nethonesdk-ios-mangopay-spm"

7. Add NethoneSDK dependency in the Package.swift file.

1
// swift-tools-version: 5.7
2
3
import PackageDescription
4
5
let package = Package(
6
    name: "Dependencies",
7
    products: [
8
        .library(
9
            name: "Dependencies",
10
            targets: ["Dependencies"]),
11
    ],
12
    dependencies: [
13
        .package(id: "Nethone.NethoneSDK", exact: "2.17.1")
14
    ],
15
    targets: [
16
        .target(
17
            name: "Dependencies",
18
            dependencies: [
19
                .product(name: "NethoneSDK", package: "Nethone.NethoneSDK")
20
            ]),
21
    ]
22
)

8. Resolve the package.

$
swift package resolve

9. Add the Dependencies package to your Xcode project

1. Open your Xcode project.
2. Navigate to File > Add Package Dependencies.
3. Click the Add Local button.
4. Select the Dependencies directory.

Installation using CocoaPods (optional)

1. Install the latest version of CocoaPods

$
sudo gem install cocoapods

2. Install Artifactory CocoaPods plugin

$
gem install cocoapods-art

3. Add the Artifactory repository to your application directory

$
pod repo-art add nethonesdk-ios-mangopay-cocoapods "https://nethone.jfrog.io/nethone/api/pods/nethonesdk-ios-mangopay-cocoapods"

4. Go to your application home directory and add the following code to your Podfile.

1
platform :ios, '12.0'
2
use_frameworks!
3
4
plugin 'cocoapods-art', :sources => [
5
    'nethonesdk-ios-mangopay-cocoapods', 'trunk'
6
]
7
8
target '<Your Target Name>' do
9
    pod 'NethoneSDK'
10
end

5. Install the pods files.

$
pod install

Version update

To update, you would first need to update the artifactory repository then the pods.

1. Update the artifactory repository.

$
pod repo-art update nethonesdk-ios-mangopay-cocoapods

2. Update the pods.

$
pod update

Manually

1. Download the latest version of NethoneSDK.xcframework from your Artifactory Repository. Find the nethonesdk-ios-mangopay repository and save it in the project folder.

2. Embed frameworks into your app target. In Xcode, go to the application target General settings. On the bottom, you can find Embedded Binaries section. Add NethoneSDK.xcframework by clicking the plus + button and choose the framework from your disk.

How to update

To update, download the new version of the NethoneSDK.xcframework from Artifactory and save it in the place as the previous version, thereby overwriting it.

Initializing the SDK

Before you can use the framework, you must set the Merchant Number which is the identification number provided to you during the onboarding process.

To do so, you need to call setMerchantNumber(...) shortly after application starts.

For example in didFinishLaunchingWithOptions:

1
import NethoneSDK
2
3
@UIApplicationMain
4
class AppDelegate: UIResponder, UIApplicationDelegate {
5
    func application(_ application: UIApplication,
6
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
7
        NTHNethone.setMerchantNumber("<your merchant number>");
8
        return true
9
    }
10
}

Profiling attempt

Attempt reference

The attemptReference is a unique, single-use identifier used to identify a specific profiling attempt. Your server will use this reference to query Nethone about the status of the attempt.

AttemptReference is generated by calling the beginAttempt function and is accessible by a static function named attemptReference.

1
let currentAttempt: String? = NTHNethone.attemptReference()

Starting an attempt

To start an attempt, use the NTHNethone.beginAttempt method.

The behavioral data collection can also be turned off by setting the configuration variable config.withoutBehavioralData to true (swift) or YES (objective-c), and passing this configuration when starting the attempt.

1
override func viewWillAppear(_ animated: Bool) {
2
    //...
3
    let config = NTHAttemptConfiguration()
4
    config.sensitiveFields = ["input"]
5
    config.withoutBehavioralData = false
6
    try? NTHNethone.beginAttempt(with: config)
7
}

Finalizing an attempt

The finalizeButtonTapped function makes sure that the necessary data has reached us. It is not recommended to terminate profiling and continue the flow until the function returns to the completion block.

1
func finalizeButtonTapped() {
2
    try? NTHNethone.finalizeAttempt(completion: { error in
3
        guard error == nil else {
4
            // Handle finalization error.
5
            // For example: internet is down
6
            return
7
        }
8
        // All data has been delivered to Nethone. Do the actual payment processing
9
    })
10
}

Sending custom attempt data

For custom data, you can use the sendCustomAttemptData method and add the options argument to specify the type of the custom data.

The available option is DataTypeJson.

1
let customData:[String: Any] = ["some_custom_data": 48151]
2
try? NTHNethone.sendCustomAttemptData(customData, options: .DataTypeJson)

Canceling an attempt

Canceling an attempt immediately stops collecting and sending data without further checking whether the relevant data has been received by us.

1
override func viewDidDisappear(_ animated: Bool) {
2
    //...
3
    try? NTHNethone.cancelAttempt()
4
}

Errors

Optional features

Text field registration

Register a text field

The registerTextField() method will register a text field to send data from it.

The function takes a mode parameter which indicates the mode in which textField will collect data. The NTHRegisterMode enum provides constants for the data collecting options for a textField when registered.

There are 3 possible options:

• NTHRegisterMode.NoneData – No behavioral or text data will be collected.
• NTHRegisterMode.ContentFree –Only behavioral data will be collected.
• NTHRegisterMode.AllData – All behavioral and text data will be collected.

The function also takes a name parameter which describes the given textField in collected data. When left as Null, the value will be determined automatically, however it might be inaccurate.

The text fields are permanently registered, which means that data from these fields will be collected during each profiling. There is no need to register fields every time during the start of an attempt.

1
@IBOutlet weak var aTextFieldToRegister: UITextField!
2
3
override func viewDidLoad() {
4
    //...
5
    NTHNethone.register(aTextFieldToRegister,
6
                        mode: .ContentFree,
7
                        name: "UserName")
8
}

Customizing data collection

To collect data only from previously registered text fields instead of all UITextFields, you need to use the registered textFields.

1
registeredTextFieldsOnly = false

IDFA permissions

The identifier for advertisers (IDFA) is a unique identifier assigned by Apple to a user’s iOS device. Advertisers are required to request permission to access the IDFA and track the user.

To use this feature, you will need to use the App Tracking Transparency (ATT) framework. You must also include a purpose string in the system prompt that explains why you’d like to track the user.

To access the values of the IDFA, you need:

• The user’s device on iOS 14.5+ .
• The user’s permission granted through the App Tracking Transparency prompt.

Location permissions

According to Apple’s Core Location documentation, to enable data location collection during profiling, the application should handle authorization from the user before profiling starts.

To collect the relevant data, the application needs consent for “When In Use” with the Full Accuracy option selected.

1
//
2
//  NTHLocationManager.swift
3
//
4
//  Copyright © 2021 Nethone. All rights reserved.
5
//
6
7
/**
8
    If the user has denied access to the location.
9
    The SDK will not show any other popup and fail to get the location data silently.
10
11
    Before you implement a permission handling module,
12
    you need to add some explanation to your's app plist.
13
14
    <key>NSLocationWhenInUseUsageDescription</key>
15
    <string>We need this to ...</string>
16
    <key>NSLocationTemporaryUsageDescriptionDictionary</key>
17
    <dict>
18
        <key>ExampleUsageDescription</key>
19
        <string>We need this to ...</string>
20
    </dict>
21
22
    If your app already uses those, you don't need to change anything.
23
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
24
    <key>NSLocationAlwaysUsageDescription</key>
25
26
    If you app uses this, then it is preferred to remove it for getting more accurate location.
27
    <key>NSLocationDefaultAccuracyReduced</key>
28
    <true/>
29
*/
30
31
import CoreLocation
32
33
class NTHLocationManager: NSObject {
34
    private static var sharedLocationManager: NTHLocationManager = {
35
        let nlm = NTHLocationManager()
36
        nlm.locationManager.delegate = nlm
37
        return nlm
38
    }()
39
40
    class func shared() -> NTHLocationManager {
41
        return sharedLocationManager
42
    }
43
44
    private let locationManager: CLLocationManager
45
46
    private override init() {
47
        locationManager = CLLocationManager()
48
    }
49
50
    func handlePermissions() {
51
        if !CLLocationManager.locationServicesEnabled() {
52
53
            //TODO: Explain to the user to turn on location services in the settings
54
            //Otherwise, it will not be possible to collect location data
55
56
            return
57
        }
58
        checkStatus()
59
    }
60
61
    private func checkStatus() {
62
        var status: CLAuthorizationStatus?
63
        if #available(iOS 14.0, *) {
64
            status = locationManager.authorizationStatus
65
        } else {
66
            status = CLLocationManager.authorizationStatus()
67
        }
68
69
        switch status {
70
        case .notDetermined:
71
            locationManager.requestWhenInUseAuthorization()
72
        case .denied:
73
74
            //TODO: Convince the user to allow access to the location data
75
            //Otherwise, it will not be possible to collect location data
76
77
            break
78
        case .restricted:
79
            break
80
        case .authorizedAlways:
81
            if #available(iOS 14.0, *) {
82
                checkAccuracy()
83
            }
84
        case .authorizedWhenInUse:
85
            if #available(iOS 14.0, *) {
86
                checkAccuracy()
87
            }
88
        default:
89
            break
90
        }
91
    }
92
93
    @available(iOS 14.0, *)
94
    private func checkAccuracy() {
95
        switch locationManager.accuracyAuthorization {
96
        case .fullAccuracy:
97
            break
98
        case .reducedAccuracy:
99
            requestFullAccuracy()
100
        default:
101
            break
102
        }
103
    }
104
105
    @available(iOS 14.0, *)
106
    func requestFullAccuracy() {
107
        locationManager
108
            .requestTemporaryFullAccuracyAuthorization(withPurposeKey: "ExampleUsageDescription")
109
            { [weak self] (error) in
110
                guard error == nil else { return }
111
112
                switch self?.locationManager.accuracyAuthorization {
113
                case .fullAccuracy:
114
                    break
115
                case .reducedAccuracy:
116
117
                    //TODO: Convince the user to allow access to a precise location data and request again
118
                    //Otherwise, it will not be possible to collect precise location data
119
120
                    break
121
                default:
122
                    break
123
                }
124
            }
125
    }
126
}
127
128
extension NTHLocationManager: CLLocationManagerDelegate {
129
    func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
130
        checkStatus()
131
    }
132
133
    func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) { }
134
}

Active call detection

The use of CallKit is prohibited in China. Due to this, Apple has introduced an additional check to make sure that the regulation is fulfilled. We made sure our solution does not use CallKit in China by using the NSLocale.regionCode function.

Apple detects the use of CallKit during the Apple Review process and makes sure the developer is aware of the regulation by rejecting the application with a message. You need to reply that your CallKit implementation is not active in China, and include a short message in the Reviewer Information section saying: “In this version and next we do not use CallKit for users in China. We detect the user’s region with NSLocale”.

Related resources