1. Python SDK Usage Guide

Before using, please read the Data Model introduction.

2. Integrate Sensors Analytics SDK

Integrate the Sensors Analytics SDK in Python code to collect and analyze user data.

We recommend using pip to manage Python projects and get the Sensors Analytics SDK:

pip install SensorsAnalyticsSDK

If you do not use pip, you can also download the source code of the Sensors Analytics SDK from GitHub.

The SDK is compatible with Python 2.6+ and Python 3.X, without relying on any third-party libraries.

2.1. Initialize the Sensors Analytics SDK

2.1.1. Get the configuration information

Get the data receiving URL as shown below:

2.1.2. Initialize the SDK in the program

In the code segment where the SDK is initialized in the program, use the instance of the Sensors Analytics SDK. In a production environment, use the ConcurrentLoggingConsumer combined with the LogAgent tool for data collection.

import sensorsanalytics # 初始化一个 Consumer，用于数据发送 # ConcurrentLoggingConsumer 是将数据写在日志文件中，再利用神策提供的 LogAgent 工具发送数据 consumer = sensorsanalytics.ConcurrentLoggingConsumer('您的日志文件路径') # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer) # 记录用户登录事件 distinct_id = 'ABCDEF123456789' sa.track(distinct_id, 'UserLogin', is_login_id=True) # 上报所有缓存数据，测试时可以调用调试数据，线上环境一般可以不调用 sa.flush() sa.close()

Before exiting the program, explicitly close using the close() method, otherwise some cached data may be lost. Now we can use the Sensors Analytics SDK normally. For more information about using the SDK, you can jump to the "Controlling the Sensors Analytics SDK" section at the end of this article.

3. Set up the Sensors Analytics SDK

The Golang SDK mainly consists of the following two components:

• SensorsAnalytics: The interface object for sending data, the constructor requires a Consumer instance
• Consumer: The Consumer handles the actual data sending

In order to allow developers to flexibly access data, the Sensors Analytics SDK implements the following Consumers:

• LoggingConsumer
• ConcurrentLoggingConsumer（Recommended）
• DebugConsumer（Test use）
• ConsoleConsumer
• DefaultConsumer
• BatchConsumer
• AsyncBatchConsumer

3.1. LoggingConsumer

Used to output data to a specified directory and cut files by day, generally used to process real-time data in Python scripts, generate log files and use LogAgent Tools such as import. Suitable for single process programs.

import sensorsanalytics # 初始化 LoggingConsumer consumer = sensorsanalytics.LoggingConsumer('/data/sa/access.log') # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer)

You can set the partition interval and the number of reserved files. The default value is 0 o 'clock every day, and all files are reserved. For details, see Parameter MeaningThe Python standard library logging. Handlers. TimedRotatingFileHandler document。

# 按小时切分，保留最近10个文件 consumer = sensorsanalytics.LoggingConsumer('/data/sa/access.log', backupCount=10, when='H')

Do not use multiple processes to write to the same log file, as this may cause data loss or confusion. If you need more than the process writing, please use the ConcurrentLoggingConsumer.

3.2. ConcurrentLoggingConsumer（Recommended）

It is used to output data to a specified directory and press it automaticallyday cut file，与 LoggingConsumer The difference is that it supports multiple processes to write to the same file. It is generally used in special multi-process scenarios such as Django and uWSGI.

import sensorsanalytics # 当缓存的数据量达到参数值时，批量向文件中写入数据 SA_BULK_SIZE = 1024 # 初始化 ConcurrentLoggingConsumer，写入文件 '/data/sa/access.log.YYYY-MM-DD' 中，日志缓冲区长度为 1024 条 consumer = sensorsanalytics.ConcurrentLoggingConsumer('/data/sa/access.log', SA_BULK_SIZE) # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer) # ... # 上报所有缓存数据，测试时可以调用调试数据，线上环境一般可以不调用 sa.flush()

Note Note the real_time_file_name parameter in the LogAgent configuration file; otherwise, data cannot be imported. Have used LoggingConsumer customer Suggestions according to the following steps to switch to ConcurrentLoggingConsumer:

Step 1 Stop LogAgent and comment out the real_time_file_name parameter in the LogAgent configuration.
Step 2 Add the suffix.YYYY-MM-DD to the real_time_file_name file in the log directory.
Step 3 switch to ConcurrentLoggingConsumer back-end application upgrade.
Step 4 Restart LogAgent.

3.3. DebugConsumer（Test use）

Used to verify that data is imported correctlydebug model detail information, please go to the relevant page to check.Note: Debug mode is set for the convenience of developers debugging mode, this mode will check the data one by one and throw an exception when the check fails, the performance is much lower than normal mode. Using the Debug mode in an online environment seriously affects performance and risks crashes. You must replace or disable the Debug mode before launching the product.

import sensorsanalytics # 神策分析数据接收的 URL SA_SERVER_URL = 'YOUR_SERVER_URL' # 发送数据的超时时间，单位秒 SA_REQUEST_TIMEOUT = 1 # Debug 模式下，是否将数据导入神策分析 # True - 校验数据，并将数据导入到神策分析中 # False - 校验数据，但不进行数据导入 SA_DEBUG_WRITE_DATA = True # 初始化 DebugConsumer consumer = sensorsanalytics.DebugConsumer(SA_SERVER_URL, SA_DEBUG_WRITE_DATA, SA_REQUEST_TIMEOUT) # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer)

3.4. ConsoleConsumer

Used to output data to standard output, usually used to process historical data in Python scripts, generate log files and import tools like Integrator Importer.

import sensorsanalytics # 初始化 ConsoleConsumer consumer = sensorsanalytics.ConsoleConsumer() # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer)

3.5. DefaultConsumer

Typically used in scenarios where small-scale historical data is imported. Since the data is sent directly over the network, if there is a network exception, it may result in data retransmission or loss, so it should not be used in any online services.Ordinary Consumer, implementing synchronous sending of data to the receiving server one by one.

import sensorsanalytics # 神策分析数据接收的 URL SA_SERVER_URL = 'YOUR_SERVER_URL' # 发送数据的超时时间，单位秒 SA_REQUEST_TIMEOUT = 1 # 初始化 DefaultConsumer consumer = sensorsanalytics.DefaultConsumer(SA_SERVER_URL, SA_REQUEST_TIMEOUT) # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer)

3.6. BatchConsumer

Typically used in scenarios where small-scale historical data is imported, or offline/parallel import of data. Since the data is sent directly over the network, if there is a network exception, it may result in data retransmission or loss, so it should not be used in any online services.Consumer that sends data in batches, and only sends the data when it reaches the specified quantity.

import sensorsanalytics # 神策分析数据接收的 URL SA_SERVER_URL = 'YOUR_SERVER_URL' # 发送数据的超时时间，单位秒 SA_REQUEST_TIMEOUT = 1 # 当缓存的数据量达到参数值时，批量发送数据 SA_BULK_SIZE = 100 # 初始化 BatchConsumer consumer = sensorsanalytics.BatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, SA_REQUEST_TIMEOUT) # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer) # 程序结束前调用 close() ，通知 Consumer 发送所有缓存数据 sa.close()

3.7. AsyncBatchConsumer

Typically used in scenarios where small-scale historical data is imported.Consumer that uses a separate thread for data sending, and asynchronously and batchly sends data over the network.

import sensorsanalytics # 神策分析数据接收的 URL SA_SERVER_URL = 'YOUR_SERVER_URL' # 初始化 AsyncBatchConsumer consumer = sensorsanalytics.AsyncBatchConsumer(SA_SERVER_URL) # 使用 Consumer 来构造 SensorsAnalytics 对象 sa = sensorsanalytics.SensorsAnalytics(consumer) # 程序结束前调用 close() ，通知 Consumer 发送所有缓存数据 sa.close()

3.8. Other settings

Importing Historical Data: By default, Sensors Analytics filters out data with occurrence time that is relatively old (e.g., more than 10 days ago, depending on the server settings). If you want to import historical data, you can enable  Time Free to bypass this restriction.

# 使用 Consumer 来构造 SensorsAnalytics 对象时，开启 Time Free sa = sensorsanalytics.SensorsAnalytics(consumer,enable_time_free = True)

4. API Interface

For documentation on using the API interface, refer to Basic API usage documentation.