目录

HiAnalytics

Class Info

Provides public methods to report user behavior data.

Public Method Summary

Qualifier and Type

Method Name and Description

void

config

Initializes Analytics Kit.

void

configWithRoutePolicy:(nonnull NSString *)routePolicy

Initializes Analytics Kit. To call this method, you must set a data processing location.

void

setReportPolicies:(nullable NSArray<HAReportPolicy *> *)policies

Sets data reporting policies.

void

onEvent:(nonnull NSString *)eventId setParams:(nonnull NSDictionary<NSString *, id> *)params

Records an event.

void

setUserProfile:(nonnull NSString *)name setValue:(nullable NSString *)value

Sets user attributes.

nullable NSDictionary<NSString *, id> *

userProfiles:(BOOL)preDefined

Obtains automatically collected or custom user attributes.

void

setAnalyticsEnabled:(BOOL)enabled

Sets whether to enable event tracking.

nonnull NSString *

AAID

Obtains the Anonymous Application ID (AAID).

void

setUserId:(nullable NSString *)userId

Sets a user ID.

void

setSessionDuration:(NSTimeInterval)milliseconds

Sets the session timeout interval.

void

clearCachedData

Clears all the collected data in the local cache.

void

setRestrictionEnabled:(BOOL)enabled

Sets whether to disable data analysis.

BOOL

isRestrictionEnabled

Checks whether data analysis is disabled.

void

setCollectAdsIdEnabled:(BOOL)isEnabled

Sets whether to collect IDFAs.

void

addDefaultEventParams:(nullable NSDictionary<NSString *, id> *)params

Adds default event parameters.

void

setMinActivitySession:(NSTimeInterval)milliseconds

Sets the minimum interval for refreshing a session when your app is running in the background.

Public Methods

[h2]config

Method

+ (void)config

Initializes Analytics Kit.

Analytics Kit will be initialized in the main thread based on your configuration.

NOTE:
  • If you have set a data processing location when calling configWithRoutePolicy and will call config after that, the location set by configWithRoutePolicy will become ineffective. Instead, the default data processing location will be used by HiAnalytics.
  • If your app will be released in multiple countries/regions, you are advised to enable multiple data processing locations and use configWithRoutePolicy to initialize the SDK. When calling configWithRoutePolicy, specify the data processing locations as required.

[h2]configWithRoutePolicy

Method

+ (void)configWithRoutePolicy:(nonnull NSString *)routePolicy

Initializes Analytics Kit.

Analytics Kit will be initialized in the main thread based on your configuration.

NOTE:
  • This method can take effect only after you have submitted a ticket online to apply for setting multiple data processing locations. For details, please refer to Submitting a Ticket Online.
  • To call the method for setting multiple data processing locations, download the latest app configuration file from AppGallery Connect. To download the file, go to Project settings and download agconnect-services.plist from the App information area.

Parameters

Name

Description

routePolicy

Data processing location.

The options are CN (China), DE (Germany), SG (Singapore), and RU (Russia).

NOTE:

The data processing location you set must have the data storage permission. Otherwise, data cannot be reported to it.

[h2]setReportPolicies

Method

+ (void)setReportPolicies:(nullable NSArray<HAReportPolicy *> *)policies

Sets data reporting policies.

Parameters

Name

Description

policies

Policy for data reporting. Four policies are supported. One or more policies can be specified.

  • onAppLaunchPolicy: An event will be reported immediately when this policy is set. After that, an event will be reported each time the app is launched.
  • onMoveBackgroundPolicy: An event will be reported when the app is switched to the background (including app exit).
  • onScheduledTimePolicy: An event will be reported at the specified interval, in seconds. The value ranges from 60 to 1800. If the specified value is beyond the value range, the boundary value is used.
  • onCacheThresholdPolicy: An event will be reported when the number of cached events reaches the threshold. The value ranges from 30 to 1000. The default value is 200. If the specified value is beyond the value range, the boundary value is used.
  • The preceding reporting policies take effect only when the debug mode is disabled.
  • The ON_MOVE_BACKGROUND_POLICY and ON_CACHE_THRESHOLD_POLICY policies are mandatory and take effect regardless of which policy is used. For the ON_CACHE_THRESHOLD_POLICY policy, you can change the threshold for reporting an event.
  • Event reporting policies will be updated if a policy setting API is called multiple times. Only the last policy set by the API is effective.
  • When reporting conditions specified by a policy are met and event reporting is triggered, the event will be cached locally if no network is available and will be reported again when reporting conditions are met next time.
  • The specified event reporting policies are saved persistently.

[h2]onEvent:setParams

Method

+ (void)onEvent:(nonnull NSString *)eventId setParams:(nonnull NSDictionary<NSString *, id> *)params

Records an event.

Parameters

Name

Description

eventId

Event ID, a string containing a maximum of 256 characters. The value cannot be empty or the ID of an automatically collected event. It can consist of digits, letters, and underscores (_), but cannot contain spaces or start with a digit.

Example: event_description10

params

Information carried in an event. The number of built-in key-value pairs in the dictionary cannot exceed 2048 and the dictionary cannot exceed 204,800 characters. Each key in the key-value pairs can consist of digits, letters, underscores (_), and the dollar sign ($), but cannot start with a digit.

[h2]setUserProfile:setValue

Method

+ (void)setUserProfile:(nonnull NSString *)name setValue:(nullable NSString *)value

Sets user attributes. The values of user attributes remain unchanged throughout the app lifecycle and during each session. A maximum of 25 user attributes are supported. If the name of an attribute set later is the same as that of an existing attribute, the value of the existing attribute is updated.

Parameters

Name

Description

name

User attribute name, a string containing a maximum of 256 characters. The value cannot be empty. It can consist of digits, letters, and underscores (_) and must start with a letter.

value

User attribute value, a string containing a maximum of 256 characters.

  • To delete user attributes, you can set value to nil for these attributes when calling setUserProfile.
  • If you delete or add an attribute, you must do it in both the app and AppGallery Connect and associate the attribute based on the attribute name.

[h2]userProfiles

Method

+ (nullable NSDictionary<NSString *, id> *)userProfiles:(BOOL)preDefined

Obtains automatically collected or custom user attributes.

NOTE:

This method cannot obtain the following automatically collected attributes: AAID and IDFA.

Parameters

Name

Description

preDefined

Indicates whether to obtain automatically collected or custom user attributes.

  • YES: Obtains automatically collected user attributes.
  • NO: Obtains custom user attributes.

Returns

Type

Description

NSDictionary<NSString *, id>

Automatically collected or custom user attributes.

[h2]setAnalyticsEnabled

Method

+ (void)setAnalyticsEnabled:(BOOL)enabled

Sets whether to enable event tracking. If this function is disabled, all cached data will be reported and no data will be recorded.

NOTE:

Parameters

Name

Description

enabled

Indicates whether to enable event tracking. The default value is YES.

  • YES: yes
  • NO: no

Sample code:

The following code is used to disable event tracking.

-(BOOL)application:(UIApplication *)applicationdidFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
  // Override point for customization after app launch.
  [HiAnalytics config];
  [HiAnalytics setAnalyticsEnabled:NO];
  return YES;
}

[h2]AAID

Method

+ (nonnull NSString *)AAID

Obtains the AAID.

Returns

Type

Description

NSString *

AAID.

[h2]setUserId

Method

+ (void)setUserId:(nullable NSString *)userId

Sets a user ID.

When this method is called, a new session will be generated if the old value of userId is not empty and is different from the new value. If you do not want to use userId to identify a user (for example, when a user signs out), you must set userId to nil.

Parameters

Name

Description

userId

Anonymous user ID, a string containing a maximum of 256 characters. It is associated with the user data by Analytics Kit. Only you can use this ID to trace a specific user, while Analytics Kit cannot.

The value cannot be empty.

NOTE:

When setting userId, comply with the HUAWEI Analytics Service Agreement and avoid using the original ID that can be used to identify a user. You are advised to use a random ID.

[h2]setSessionDuration

Method

+ (void)setSessionDuration:(NSTimeInterval)milliseconds

Sets the session timeout interval. A new session will be generated when an app is running in the foreground but the interval between two adjacent events exceeds the specified timeout interval.

Parameters

Name

Description

milliseconds

Session timeout interval, in milliseconds.

The interval ranges from 5 seconds to 5 hours. If the specified value is beyond the value range, the boundary value is used. The default value is 1800000 (that is, 30 minutes).

[h2]clearCachedData

Method

+ (void)clearCachedData

Clears all the collected data in the local cache, including data that failed to be sent.

Data configured through the following APIs will be cleared:

NOTE:

Calling this method will reset the AAID. In Analytics Kit 6.0.0 and later versions, calling this method will also reset the user ID.

[h2]setRestrictionEnabled

Method

+ (void)setRestrictionEnabled:(BOOL)enabled

Sets whether to disable data analysis. The default value is NO, which indicates that data analysis is enabled.

Parameters

Name

Description

enabled

Indicates whether to disable data analysis. The default value is NO.

  • YES: yes
  • NO: no

[h2]isRestrictionEnabled

Method

+ (BOOL)isRestrictionEnabled

Checks whether data analysis is disabled.

Returns

Type

Description

BOOL

YES if data analysis is disabled; NO otherwise.

[h2]setCollectAdsIdEnabled

Method

+ (void)setCollectAdsIdEnabled:(BOOL)isEnabled

Sets whether to collect IDFAs.

Parameters

Type

Description

isEnabled

Indicates whether to collect IDFAs.

  • YES: yes
  • NO: no

[h2]addDefaultEventParams

Method

+ (void)addDefaultEventParams:(nullable NSDictionary<NSString *, id> *)params

Adds default event parameters. These parameters will be added to all events except the automatically collected events. If the name of a default event parameter is the same as that of an event parameter, the event parameter will be used.

Parameters

Name

Description

params

Default event parameters.

A maximum of 100 key-value pairs are supported. The key in each key-value pair can contain a maximum of 256 characters and can consist of only digits, letters, and underscores (_), but cannot start with a digit. The value in each key-value pair can contain a maximum of 256 characters.

NOTE:
  • If params is set to nil, all cached default event parameters will be cleared. If the value in a passed key-value pair is of the NSNull type, the corresponding default event parameter will be deleted. If the key in a passed key-value pair already exists, the corresponding default event parameter will be updated.
  • The number and value length of default event parameters will be counted in onEvent, so pay attention to the parameter usage restrictions.

[h2]setMinActivitySession

Method

+ (void)setMinActivitySession:(NSTimeInterval)milliseconds

Sets the minimum interval for refreshing a session when your app is running in the background. When the app is running in the background for a period of time longer than the specified threshold, a new session will be generated when the app switches to the foreground.

Parameters

Name

Description

milliseconds

Minimum interval for refreshing a session, in milliseconds.

The interval ranges from 5 seconds to 5 hours. If the specified value is beyond the value range, the boundary value is used. The default value is 30000 (that is, 30 seconds).