Advanced configuration

The PAPulse SDK offers a host of config methods (starting with configSet) that allow you to pass additional values to get more accurate data with more detail or change predefined business logic.

Configuration methods

All of the required and optional methods, listed below, should be called before initiating a session by calling PAAnalytics.start().

`configSet(appName:)`

The PAPulse SDK requires the invocation of a single mandatory method during initialization, which is configSetAppName or configSetAppName:groupName. This method sets the app name (Bundle ID), which is a necessary parameter on the backend side for retrieving the corresponding Remote Settings. The optional groupName parameter is used for an app group (App Group), facilitating data sharing between the main app and related App Extensions through shared UserDefaults or shared keychain.

PAAnalytics.configSet(appName: "com.yourappname.studio")

PAAnalytics.configSet(appName: "com.yourappname.studio", groupName: "extension_name")

`configSet(allowIDFA:)`

In compliance with policies such as ATT (App Tracking Transparency) or GDPR (General Data Protection Regulation), the PAPulse SDK does not collect or transmit an IDFA (Identifier for Advertisers) identifier by default. However, if you wish to obtain more precise reporting regarding user behavior and engagement, you can enable the collection and transmission of this data using the configSetAllowIDFA method.

PAAnalytics.configSet(allowIDFA: true)

Danger Zone

Please note that the collection and usage of PII (Personally Identifiable Information), such as the IDFA (Identifier for Advertisers), can potentially violate user privacy and lead to legal issues in certain countries, including the European Union (EU). It is crucial to strictly adhere to all government laws and regulations before invoking the configSetAllowIDFA function or engaging in any data collection practices.

`configSet(analyticsEnabled:)`

To enable Analytics Tracking (events logging), simply call the configSetAnalyticsEnabled method with the appropriate parameter to set it to true before starting the session. By default, Analytics Tracking logging is enabled. It means all external and internal calls of logEvent() methods are processed by the PAPulse SDK. The fired events are then saved in a local database, and the SDK transmits them to the analytics backend. However, the actual transmission of events occurs when a certain threshold count is reached.

PAAnalytics.configSet(analyticsEnabled: true)

`configSet(analyticsURL:)`

By default, all triggered events and attributes are sent to https://analytics.picsart.com/. However, if you need to change the URL for debugging purposes or if a different URL has been assigned to your application, you should modify it using the configSetAnalyticsURL function. This function allows you to specify a custom URL for sending the analytics data.

PAAnalytics.configSet(analyticsURL: <YOUR_ASSIGNED_URL>)

`configSet(apiKey:)`

If you have an associated API key, you can pass it to the SDK using the configSetApiKey method. This allows the SDK to prepare the fetching of a special edition of Remote Settings.

PAAnalytics.configSet(apiKey: "3892002133321")

`configSet(asyncSettingsFetchingBehavior:)`

Configures the behavior for async tagged settings requests when timeout is exceeded. This method sets how the Analytics SDK handles situations where fetching tagged settings takes longer than the specified timeout period. The behavior determines whether the SDK should terminate the request or continue fetching in the background. The default SDK behavior is .terminateOnExpectation if this method is not called.

.terminateOnExpectation - Terminates the settings request when the timeout is exceeded. When this behavior is selected, the Analytics SDK will terminate the outgoing tagged settings request if the fetching time exceeds the timeout specified by the user in the corresponding function call. In this case, the SDK will immediately call the completion block with either:
- The default value (if provided)
- An outdated value from the old cache (if available)
- nil (if no default or cached value exists) The network request will be cancelled.
.continueUntilFinished - Continues the settings request even when the timeout is exceeded. When this behavior is selected, the Analytics SDK will continue the outgoing tagged settings request regardless of whether the fetching time exceeds the timeout specified by the user. The SDK will immediately call the completion block with either:
- The default value (if provided)
- An outdated value from the old cache (if available)
- nil (if no default or cached value exists) However, the network request will continue running in the background. Once the request completes successfully, the new settings will be saved into the temporal cache for future use.

PAAnalytics.configSet(asyncSettingsFetchingBehavior: .continueUntilFinished)

`configSet(attributeLoggingEnabled:)`

To enable User Attributes logging, simply call the configSetAttributeLoggingEnabled method with the appropriate parameter to set it to true before starting the session. By default, User Attributes logging is disabled. It means all external and internal calls of logAttribute() methods are ignored by the PAPulse SDK.

PAAnalytics.configSet(attributeLoggingEnabled: true)

`configSet(autoEventsConfig:)`

To enable automatic event logging, simply call the configSetAutoEventsConfig method with the appropriate parameter that specifies the types of auto events to be logged by the SDK. The autoEventsConfig parameter holds a set of granular auto event types related to specific UIKit controls and user interactions.

Auto event type-	Purpose
`viewController`	Allow `"page_load"` and `"page_view"` event tracking for all `UIViewController` instances
`buttonClick`	Allow `"click"` event tracking for all `UIButton` instances
`switchControlClick`	Allow `"click"` event tracking for all `UISwitch` instances
`sliderControlClick`	Allow `"click"` event tracking for all `UISlider` instances
`stepperControlClick`	Allow `"click"` event tracking for all `UIStepper` instances
`segmentedControlClick`	Allow `"click"` event tracking for all `UISegmentedControl` instances
`barButtonClick`	Allow `"click"` event tracking for all `UIBarButtonItem` instances
`tableViewClick`	Allow `"click"` event tracking when the user taps any cell in a `UITableView` instance
`collectionViewClick`	Allow `"click"` event tracking when the user taps any cell in a `UICollectionView` instance
`tableViewImpression`	Allow `"items_impression"` event tracking when `UITableView` cells remain visible on the screen
`collectionViewImpression`	Allow `"items_impression"` event tracking when `UICollectionView` cells remain visible on the screen
`scroll`	Allow `"scroll"` event tracking when the user scrolls any `UIScrollView` or its subclass
`gesture`	Allow `"gesture"` event tracking when any gesture recognizer detects a "tap", "pinch", or "move" gesture
`revenueTracking`	Allow various IAP-related events associated with transactions processed via StoreKit

`configSet(debugConsoleLogging:)`

It is very important for app developers and QA engineers to have the ability to investigate debug message logs in order to identify various types of issues and understand the current workflow or user behavior. The SDK provides a method called configSetDebugConsoleLogging, which allows to specify the destination of the debug messages generated by the SDK during its operation.

There are several options for the destination of debug messages:

.disable this is the default option, where service debug messages from the SDK are not displayed.
.system the debug messages are directed to the system console within the Xcode IDE.
.consoleApp the debug messages are sent to a special app within the Xcode IDE called "Console App". This provides a dedicated interface for viewing and analyzing the debug messages separately from other system logs.

PAAnalytics.configSet(debugConsoleLogging: .consoleApp)

`configSet(debugModeEnabled:)`

To enable Debug Mode, simply call the configSetDebugModeEnabled method with the appropriate parameter to set it to true before starting the session. By default, Debug Mode is disabled. Enabling Debug Mode adds a special flag to all fired events and attributes, marking them for distinct processing on the analytics backend.

PAAnalytics.configSet(debugModeEnabled: true)

`configSet(directSendEnabled:)`

To enable Direct Send Mode, simply call the configSetDirectSendEnabled method with the appropriate parameter to set it to true before starting the session. By default, Direct Send Mode is disabled.

Enabling Direct Send Mode in the PAPulse SDK switches the SDK to an alternative logic where each fired event is immediately sent to the backend server as soon as it is tracked, without waiting for the batch threshold to be reached. Direct Send Mode is useful in scenarios where real-time event tracking and immediate backend processing are required for debug purposes.

PAAnalytics.configSet(directSendEnabled: true)

Keep in mind

It is recommended to use Direct Send mode for testing and debugging purposes only, particularly in QA and Enterprise builds. Enabling Direct Send mode allows for immediate transmission of each fired event to the backend server as it occurs. However, it is important to exercise caution when enabling this mode for live users. Direct Send mode can generate a higher volume of requests and may impact server load and data processing. If you decide to enable Direct Send mode for live users, it is crucial to closely monitor and control the process to ensure it does not negatively impact the user experience or overall system performance.

`configSet(eventsBatchCount:)`

The analytics data, which includes fired events, attributes, and network metrics, is sent in batches. This batching approach is implemented to optimize network traffic and manage backend high load. To initiate the sending of a batch, there is a minimum threshold that needs to be reached. By default, it is set to 100. You have the option to modify this number by using the configSetEventsBatchCount configuration method.

PAAnalytics.configSet(eventsBatchCount: 25)

`configSet(httpReportEnabled:)`

To enable HTTP Reporting feature, simply call the configSetHTTPReportEnabled method with the appropriate parameter to set it to true before starting the session. By default, HTTP Reporting Mode is disabled.

Enabling the HTTP Reporting feature allows for the collection of network request metrics, specifically HTTP/HTTPS request and response metrics (response times, request sizes, and status codes). By enabling HTTP Reporting, you can gather these metrics and transmit them to the analytics backend. The collected network request metrics are valuable for monitoring and optimizing the performance.

PAAnalytics.configSet(httpReportEnabled: true)

`configSet(httpReporterURL:)`

By default, all network metrics (HTTP\HTTPS request and response metrics) are sent to https://analytics.picsart.com/requests. However, if you need to change the URL for debugging purposes or if a different URL has been assigned to your application, you should modify it using the configSetHTTPReporterURL function. This function allows you to specify a custom URL for sending this data.

PAAnalytics.configSet(httpReporterURL: <YOUR_ASSIGNED_URL>)

`configSet(languageCode:)`

You can use this method to prepare a request for fetching Remote Settings specific to a particular language group. By invoking this method with the appropriate parameters, you can tailor the request to retrieve the desired Remote Settings.

PAAnalytics.configSet(languageCode: "fr")

`configSet(options:)`

You can use the configSetOptions method to configure several parameters within a single call, instead of using multiple configuration methods sequentially. Another use case is supporting multiple configurations or projects, such as beta and live versions of the app. The options parameter is an instance of the PAAnalyticsOptions object, which is initialized with the path to a prepared .plist file located in the main bundle. This file contains supported key-value pairs with predefined keys that the Analytics SDK can read and use to configure itself during the initialization phase. All key-value pairs inside the mentioned plist file are considered optional.

List of supported self-describing keys:

"APNS_TOKEN_TRACKING"  - value can contain a boolean flag that allows the SDK to collect and transfer the APNS token for push notifications delivery
"ANALYTICS_URL" - value can contain a string URL of the tracked events receiver. This key may be used as a substitution for a standalone `configSet(analyticsURL:)` call.
"HTTP_REPORTER_URL" - value can contain a string URL used to transfer collected HTTP requests/responses metric. This key may be used as a substitution for a standalone `configSet(httpReportEnabled:)` call.
"SETTINGS_URL" - value can contain a string URL that is used to fetch Remote Settings . This key may be used as a substitution for a standalone `configSet(settingsURL:)` call
"APP_BUNDLE" - value can contain a bundle app name. This key may be used as a substitution for a standalone `configSet(appName:)` call.
"APP_GROUP" - value can contain an app group name. This key may be used as a substitution for a standalone `configSet(appName:groupName)` call. "APP_BUNDLE" key should be set as well.

`configSet(revenueDebugEnabled:)`

To enable Debug Mode for Revenue Tracking in the PAPulse SDK, you can use the configSetRevenueDebugEnabled method. By default, this mode is disabled. By calling the configSetRevenueDebugEnabled method with the appropriate parameter set to true before starting the session, you can enable Debug Mode for Revenue Tracking.

Enabling Debug Mode for Revenue Tracking provides you with the ability to inspect all revenue-related events on the Analytics Debug Screen. This screen can be accessed using the PAAnalyticsRevenueEventsViewController view controller, which allows to analyze revenue-related events in a debugging context.

PAAnalytics.configSet(revenueDebugEnabled: true)

`configSet(revenueTracking:)`

To enable revenue tracking, which involves updating StoreKit and StoreKit2 transaction statuses without any your private or financial information, you can use the configSetRevenueTracking method.

To track the status updating of all In-App Purchases (IAP):

PAAnalytics.configSet(revenueTracking:[])

or to track the status updating of specific In-App Purchases (IAPs) only:

PAAnalytics.configSet(revenueTracking:["com.example.exampleapp.exampleSubscription1", "com.example.exampleapp.exampleConsumable1"])

`configSet(sessionTimeout:)`

The PAPulse SDK uses the concept of a session as a common parameter for all events triggered while the current session is active. It can be likened to an umbrella term that encompasses multiple events within a specific timeframe. When a user transitions from the foreground to the background mode and then returns to the foreground, the session may change if the user remained in the background for an extended period of time.

You have the ability to define a time threshold using the configSetSessionTimeout method. This threshold in seconds determines whether the session remains the same or gets updated based on the duration the application spent in the background mode. Default value is 5 mins (300 seconds).

On the backend side, sessions are a primary pattern for analyzing the sequential chain of tracked events. They provide insights to describe or predict user behavior, allowing for comprehensive analysis and understanding of user interactions with the application.

PAAnalytics.configSet(sessionTimeout: 600)

`configSet(settingsURL:)`

By default, Remote Settings are fetched from https://optifyr.com/api/settings. However, if you need to change the URL for debugging purposes or if a different URL has been assigned to your application, you should modify it using the configSetSettingsURL function. This function allows you to specify a custom URL for corresponding Remote Settings getting.

PAAnalytics.configSet(settingsURL: <YOUR_ASSIGNED_URL>)

`configSet(signingKey:)`

To enable the signing of outgoing SDK network requests with a digital signature, you can use the configSetSigningKey method. However, it's important to note that you'll need to contact your manager in order to obtain a dedicated private key specifically for your application. This private key is necessary to enable the signing functionality.

PAAnalytics.configSet(signingKey: "792957e913140545eb5bcbe0776a2501996d066de0ea59480943577388adab27:1")

`configSet(subscriptionStatus:)`

To include subscription status information in the Remote Settings request, you should provide it before starting the session. Additionally, whenever there is a change in this status, you need to provide it to the SDK again. And this udated status might be used for Remote Settings updating in background mode. It's important to note that this value is not persisted between app launches. Therefore, your app should provide the status as soon as possible after launch and invoke the method again with the new status once it is obtained. By default, the status is set to unknown.

PAAnalytics.configSet(subscriptionStatus: .subscribed)

`configSet(subscriptionStatusUpdate:)`

Instead of making an explicit configSet(subscriptionStatus:) API call to set the current subscription status, you can configure a closure that the Analytics SDK will call to retrieve the current subscription status from the app on demand.

PAAnalytics.configSet(subscriptionStatus: {
      Store.isSubscribed ? .subscribed : notSubscribed
   }
)

`configSet(timeInterval:)`

The PAPulse SDK respects the specified time interval between the sending of analytics data, including fired events and attributes, to the analytics backend for further processing. The default time interval is set to 60 seconds, meaning that events are transmitted to the backend every 60 seconds. However, you have the flexibility to adjust this time interval by using the configSetTimeInterval configuration method. This allows you to customize the frequency at which the events are sent to the backend according to your specific needs.

PAAnalytics.configSet(timeInterval: 10)

`configSet(userID:)`

If you have a logged in user, you can attach their ID to logged events by supplying user ID to the SDK with configSetUserId.

PAAnalytics.configSet(userID: "160817609001102")

Management methods

The optional methods listed below can be called at any time.

`disableAnalytics()` and `enableAnalytics()`

When you need to disable the collection, storage, and sending of analytics data(events, attributes, network metrics), you can call the disableAnalytics method:. Invoking this method will effectively disable the entire analytics functionality of the SDK, ensuring that no data is collected, saved, or transmitted to the backend server.

PAAnalytics.disableAnalytics()

After disabling the analytics functionality, you can enable it again

PAAnalytics.enableAnalytics()

`disableAttributeLogging()` and `enableAttributeLogging()`

If you have already configured the Pulse SDK Attribute Logging feature using the configSetAttributeLoggingEnabled method, you have the ability to manage the logging logic for user attributes. By default, this feature is disabled, which means that all external and internal calls to logAttribute() methods are rejected by the PAPulse SDK and not tracked.

PAAnalytics.disableAttributeLogging()

After disabling the Attribute Logging functionality, you can enable it again

PAAnalytics.enableAttributeLogging()

`disableDebugMode()` and `enableDebugMode()`

If you want to disable Debug Mode, which is disabled by default, you can achieve this by calling the disableDebugMode method. Enabling Debug Mode logic adds a special flag to all fired events and attributes, and causes a distinct processing pipeline on the analytics backend. Disabling Debug Mode removes this special flag and reverts to the standard processing pipeline for events and attributes.

PAAnalytics.disableDebugMode()

After disabling the Debug Mode functionality, you can enable it again

PAAnalytics.enableDebugMode()

`disableDirectSend()` and `enableDirectSend()`

You have the flexibility to choose the most suitable mode for sending the collected analytics data. By default, the SDK follows the Batch Send mode, where it waits to accumulate a certain threshold of events before sending them as a batch in one packet to the backend server. You have the option to enable Direct Send mode. In Direct Send mode, each fired event is immediately sent to the backend server as soon as it is tracked, without waiting for the batch threshold. By default, Direct Send mode is disabled. You can enable Direct Send mode by calling the enableDirectSend method.

PAAnalytics.disableDirectSend()

After disabling the Direct Send Mode functionality, you can enable it again

PAAnalytics.enableDirectSend()

`disableHTTPReport()` and `enableHTTPReport()`

If you want to disable HTTP reporting, which involves collecting network request metrics, you can do so by calling the disableHTTPReport method.

PAAnalytics.disableHTTPReport()

After disabling the HTTP reporting functionality, you can enable it again

PAAnalytics.enableHTTPReport()

`disableRevenueTracking()` and `enableRevenueTracking()`

If you have already configured the Pulse SDK Revenue Tracking feature and started collecting events, you have the option to pause the collection of Revenue Tracking events for a specific period of time. When the Revenue Tracking collection is paused, all In-App Purchases and Subscriptions emitted by StoreKit will be ignored by the SDK.

PAAnalytics.disableRevenueTracking()

After disabling the Revenue Tracking functionality, you can enable it again

PAAnalytics.enableRevenueTracking()

`forceFlush()`

To send all collected events and attributes immediately, you can call the following method forceFlush. Invoking this method triggers the immediate sending of all accumulated events and attributes frol local database to the backend server. This can be useful in scenarios where you want to ensure that the data is sent promptly instead of waiting for the regular batch sending interval.

PAAnalytics.forceFlush();

Advanced tuning

`sampleWith(sampleSize:)`

The PAPulse SDK provides a sampling mechanism, allowing you to target a fraction of users based on their Device ID. This sampling mechanism remains consistent between launches. It can be particularly useful when you want to test a new feature on only a fraction of the devices. Users are evenly divided into 10,000 buckets, and you have the flexibility to choose how many of those buckets will execute the provided code. This enables you to control the percentage of users who will experience the specific functionality or feature.

Sampling value	Percentage of affected devices
1	0.01%
10	0.1%
100	1%
2500	25%
5000	50%
10000	100%

PAAnalytics.sampleWith(sampleSize: 100) {
  // code that will be run just for `100 / 10000` of the users, so for `1%` of the users
}

Advanced Behavior

`PA_NOATT`

The App Store has different policies for certain countries. For instance, the use of AppTrackingTransparency may be restricted to comply with local laws prohibiting device tracking. By default, the PAPulse SDK imports and calls methods from this system framework. However, you can disable this behavior to prevent the import and usage of the AppTrackingTransparency framework.

The desired behavior is controlled via the PA_NOATT user-defined build setting:

If PA_NOATT is defined, AppTrackingTransparency is not imported.
If PA_NOATT is not defined, AppTrackingTransparency is imported and used as expected.

Configuring `PA_NOATT` in CocoaPods

If you use CocoaPods to manage external dependencies, you have the option to set the PA_NOATT flag:

Use a specialized pod variant by specifying pulse-ios/AnalyticsNoATT in your Podfile instead of the default pulse-ios:
```
pod "pulse-ios/AnalyticsNoATT"
```

Configuration methods
Management methods
Advanced tuning
- sampleWith(sampleSize:)
Advanced Behavior
- PA_NOATT
- Configuring PA_NOATT in CocoaPods

Advanced configuration

Configuration methods​

configSet(appName:)​

configSet(allowIDFA:)​

configSet(analyticsEnabled:)​

configSet(analyticsURL:)​

configSet(apiKey:)​

configSet(asyncSettingsFetchingBehavior:)​

configSet(attributeLoggingEnabled:)​

configSet(autoEventsConfig:)​

configSet(debugConsoleLogging:)​

configSet(debugModeEnabled:)​

configSet(directSendEnabled:)​

configSet(eventsBatchCount:)​

configSet(httpReportEnabled:)​

configSet(httpReporterURL:)​

configSet(languageCode:)​

configSet(options:)​

configSet(revenueDebugEnabled:)​

configSet(revenueTracking:)​

configSet(sessionTimeout:)​

configSet(settingsURL:)​

configSet(signingKey:)​

configSet(subscriptionStatus:)​

configSet(subscriptionStatusUpdate:)​

configSet(timeInterval:)​

configSet(userID:)​

Management methods​

disableAnalytics() and enableAnalytics()​

disableAttributeLogging() and enableAttributeLogging()​

disableDebugMode() and enableDebugMode()​

disableDirectSend() and enableDirectSend()​

disableHTTPReport() and enableHTTPReport()​

disableRevenueTracking() and enableRevenueTracking()​

forceFlush()​

Advanced tuning​

sampleWith(sampleSize:)​

Advanced Behavior​

PA_NOATT​

Configuring PA_NOATT in CocoaPods​