SDK iOS

SDK iOS

Last updated: August 30th, 2024

Introduction

The purpose of this manual is to provide all the necessary information for installing and using the tool in applications developed for the iOS platform.

This SDK is written in ObjC and collects data (information and location) from the device and sends it to ClearSale. All collected information is related only to the device, with no relation to the integrated application.

The information on geolocation and IDFA (Identifier for advertisers) depends on the permission granted by the device user, Geolocation in this case, it is necessary for the application to request access to the user's location information (the SDK does not request permission). If the application does not request access or the user does not grant permission for location, the GeoLocation information will not be captured.

The SDK respects Apple's privacy policy for capturing device data and the level of permission granted by the user (device user).

Checksum

Package Digest
CSBehavior MD5: 2329818ab396724b0b91362c7abced5a6a849deb

To check the checksum of the downloaded artifact, check the podfile.lock after running the pod install command in your project.

Checksum

Package Digest
CSBehavior MD5: 53dd028224a73c0ad9043899fb9def50dcfefc69

To check the checksum of the downloaded artifact, check the podfile.lock after running the pod install command in your project.

Checksum

Package Digest
CSBehavior MD5: 0194c7a4a2a0794a823fd7b1540504eb5e814b43

To check the checksum of the downloaded artifact, check the podfile.lock after running the pod install command in your project.

Checksum

Package Digest
CSBehavior MD5: 0194c7a4a2a0794a823fd7b1540504eb5e814b43

To check the checksum of the downloaded artifact, check the podfile.lock after running the pod install command in your project.

Package Installation

Package Installation

  • CocoaPods

The pod is available in a private repository. To use it, follow the example below for the PodFile:

source 'https://dev.azure.com/CS-PublicPackages/Behavior/_git/BehaviorAnalytics.SDK.IOS.Specs'
use_frameworks!

target 'PROJECT_NAME' do
pod 'CSBehavior', '3.0.1'

end

Package Installation

  • CocoaPods

The pod is available in a private repository. To use it, follow the example below for the PodFile:

source 'https://dev.azure.com/CS-PublicPackages/Behavior/_git/BehaviorAnalytics.SDK.IOS.Specs'
use_frameworks!

target 'PROJECT_NAME' do
pod 'CSBehavior', '3.0.2-rc.1'

end

Package Installation

  • CocoaPods

The pod is available in a private repository. To use it, follow the example below for the PodFile:

source 'https://CS-PublicPackages@dev.azure.com/CS-PublicPackages/Behavior/_git/BehaviorAnalytics.SDK.IOS.Specs'
use_frameworks!

target 'PROJECT_NAME' do
pod 'CSBehavior', '4.0.10'

end

Package Installation

  • CocoaPods

The pod is available in a private repository. To use it, follow the example below for the PodFile:

source 'https://CS-PublicPackages@dev.azure.com/CS-PublicPackages/Behavior/_git/BehaviorAnalytics.SDK.IOS.Specs'
use_frameworks!

target 'PROJECT_NAME' do
pod 'CSBehavior', '5.0.0'

end
Project Setup

Project Setup

Instructions for setting up the framework in the project:

  1. Open the project editor, select the project, and in the “Build Settings” tab add the flag “-ObjC” to the “Other Linker Flags” setting.

  2. Add the following entries to the target project's Info.plist file:
    
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>clearsale.com.br</key>
            <dict>
                <key>NSTemporaryExceptionMinimumTLSVersion</key>
                <string>TLSv1.2</string>
            </dict>
        </dict>
    </dict>
    
    <key>NSUserTrackingUsageDescription</key>
    <string>Explanation of why the user needs to grant permission.</string>
                        

  3. For projects developed in Objective-C import @import CSBehavior; in the file where you want to use the framework.
    For projects developed in Swift import <CSBehavior/CSBehavior.h> in the project's bridging header.

  4. To request IDFA collection permission, add the following code snippet:

    Objective-C
    
    #import <AppTrackingTransparency/AppTrackingTransparency.h>
    #import <AdSupport/AdSupport.h>
    
    if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        }];
    }
                        

    Swift
    
    import AppTrackingTransparency
    
    if #available(iOS 14, *) {
        ATTrackingManager.requestTrackingAuthorization { _ in
        }
    }
                        
CSBehavior Class

CSBehavior Class

CSBehavior is the class responsible for collecting information.

Constructors: this class does not have public constructors. The instance must be created through a static method.


  • Static Method
Method Name Description
(CSBehavior *)getInstance:(NSString *)toApp Obtains the instance of the Behavior class for an AppKey.
It is necessary to pass the AppKey (value provided by ClearSale) as a parameter.
  • Other Methods
Method Name Description
(NSString *)generateSessionId Generates and returns a session identifier. This method should be used only if the application does not generate unique identifiers for each collection.
(void)collectDeviceInformation:(NSString *)toSessionId Collects device information linking it to the session value. It is necessary to pass the SessionId as a parameter.
  • If you do not have your own value for the SessionID, use the method generateSessionId().
  • The maximum length of the SessionID to be used is 128 characters.
  • The minimum length of the SessionID to be used is 6 characters.
  • An exception will be thrown if the passed sessionID value is not valid.
(void)sendEvent:(CSBUserEventType)eventType :(NSString *)sessionId Responsible for sending a specific user event associated with a session (beta version).
(void)allowSecurity() Allows the activation of security features in the behavior manager.
Security Module
Once the security module is activated, a semi-annual update becomes mandatory. Pay attention to the update period.

Security Module

The iOS SDK security module consists of a series of features aimed at protecting our products and services against attacks.

Usage

This module is available from SDK version 5.0.0. To enable it, you need to call the new method allowSecurity() before collection.

Swift

var behavior: CSBehavior = CSBehavior.getInstance("APP_KEY");
behavior.allowSecurity();
behavior.collectDeviceInformation("SESSION_ID");
        
Objective-C

CSBehavior *behavior = [[CSBehavior getInstance] @"APP_KEY" ];
[behavior allowSecurity];
[behavior collectDeviceInformation: @"SESSION_ID"];
        

Update Flow

The security module has a lifecycle that allows the application to be more secure. By using this module, there will be a requirement to always be on the latest version available, with release dates in April and October of each year.

These versions are valid for 6 months. For proper functioning, it is necessary to update before the previous version expires.

Examples

Examples

ObjC with SessionId value

CSBehavior *behavior = [CSBehavior getInstance:@"APP_KEY"];
[behavior collectDeviceInformation:@"SESSION_ID"];
            
ObjC without SessionId value

CSBehavior *behavior = [CSBehavior getInstance:@"APP_KEY"];
NSString *sessionId = [behavior generateSessionId];
[behavior collectDeviceInformation:sessionId];
            
Swift with SessionId value

var behavior: CSBehavior = CSBehavior.getInstance("APP_KEY")
behavior.collectDeviceInformation("SESSION_ID")
            
Swift without SessionId value

var behavior: CSBehavior = CSBehavior.getInstance("APP_KEY")
var sessionId: NSString = behavior.generateSessionId()
behavior.collectDeviceInformation(sessionId)
            
Example Project

Example Project

You can view the SDK implementation in an example project by clicking here.

FAQ

FAQ

Click here to access our FAQ

Privacy Details

Data usage

All information collected by ClearSale's SDK are exclusively for the purpose of fraud prevention and user protection, adherent to the security and privacy policies of Google and Apple platfoms and the LGPD. Therefore, this information must be in the application privacy policy.

Data Type Collected

ClearSale's SDK collects the following device information:

  • Precise location (when allowed by user);
  • Device advertising identification (when allowed by user);
  • Device physical/hardware characteristics (such as display, battery, keyboard, disk space, model, device name);
  • Device software characteristics (such as version, language, build, parental control);
  • Network information (such as connections, IP);
  • SimCard carrier.

Google Privacy Policy
Apple Privacy Policy
License

Use License

By downloading and using our SDK you are agreeing to the following license.

Copyright © 2024 ClearSale

All rights are reserved, permission is granted to use the software as is, and no modification or copying for any purpose is permitted. The Software is licensed in its current configuration “as is” and without warranty of any kind, either express or implied, including, but not limited to, warranties of merchantability, fitness for a particular purpose and non-infringement of patented rights. Under no circumstances may the Copyright holders be held liable for damages, losses, causes of action, whether in contract or tort, or other tortious action arising from the use of the Software or other actions related to this Software without the prior written authorization of the Copyright holder.