diff --git a/README.md b/README.md index 634810f..2674f45 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,22 @@ SDK : [interakt-track-python](https://pypi.org/project/interakt-track-python/) Install `interakt-track-python` using pip pip install interakt-track-python - + ## Authentication -Inside your app, you’ll want to **set your** `api_key` before making any track calls: +Inside your app, you’ll want to set your `api_key` before making any track calls: + +To find your API key, + +- go to your interakt account's Settings --> Developer Settings + +- copy the Secret Key. + +- Make sure you base64 decode this Secret Key (you may choose to do that from [Base64 Decode and Encode- online](https://www.base64decode.org/) ) + +- Erase the ':' at the end of the base64 decoded key + +- Use this key + ``` import track @@ -30,21 +43,23 @@ track.debug = True track.on_error = on_error ``` ### All Settings: -|Settings name|Type|Default value|Description| -|--|--|--|--| -|sync_mode|bool|False|When `True`, calls the track API **synchronously**. When `False`, calls the track APIs **asynchronously** using a Queue.| -|debug|bool|False|To turn on debug logging| -|timeout|int|10|Timout for track API calls| -|max_retries|int|3|Number of API retries in case API call fails due to some error| -|max_queue_size|int|10000|Max Queue size| -|on_error|function|None|Callback function which is called whenever an error occurs in **asynchronous** mode +| Settings name | Type | Default value | Description | +| -------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ | +| sync_mode | bool | False | When `True`, calls the track API **synchronously**. When `False`, calls the track APIs **asynchronously** using a Queue. | +| debug | bool | False | To turn on debug logging | +| timeout | int | 10 | Timout for track API calls | +| max_retries | int | 3 | Number of API retries in case API call fails due to some error | +| max_queue_size | int | 10000 | Max Queue size | +| on_error | function | None | Callback function which is called whenever an error occurs in **asynchronous** mode | # APIs ## User -The track `user` call lets you tie a user to their actions and record traits about them. It includes a unique **User ID** or **Phone Number and Country Code** any optional traits you know about them. +The user track API allows customers to record the attributes specific to the user. They can record specific user properties (attributes) such as user id, email id, phone number, name etc. Customers can call the usertrack API when a new user account is created on their website/app/CRM. For example: + + +**For adding a new user to your interakt dashboard**, the following payload could be sent in the API call: -Example `user` call: ``` track.user( user_id="", @@ -53,44 +68,199 @@ track.user( traits={ "name": "John Doe", "email": "john@email.com", - "age": 24 + "age": 24, + “dob”: “1998-01-01” } ) ``` -#### The `user` call has the following fields: -|Field|Data type|Description| -|--|--|--| -|user_id|str or int|The ID for the user in your database.| -|country_code|str|country code for the phone_number (default value is "+91")| -|phone_number|str|phone_number without country_code (eg: "9876598765")| -|traits|dict|A dict of traits you know about the user. Things like: `email`, `name` or `age`| -**NOTE:** Atleast one of these two is required for user identification : +The different user attributes (traits) can be of the following data types: String, Numbers, Boolean, Datetime, List. **Check out the different filter options available in interakt, for different trait types -** [link](https://ik.imagekit.io/z4utvq9kty5/interakt_filters_K5dMwG4qe.pdf). +‍
+
+**Note\*\***: Specifying either the **user Id** or **phoneNumber (with countryCode)** is **Mandatory** +
+‍
+The above API call records the “userId” or “phoneNumber” (with “countryCode”) as a unique identifier for the user and also adds attributes such as name, email, dob. - - **user_id**, OR - - **phone_number** with **country_code** + + + + + + -## Event -`event` track API lets you record the actions your users perform. Every action triggers what we call an “event”, which can also have associated properties. + + + + + + + + + + + + + + + + + + + + -Example `event` call: + + + + + + + + + + + + + + +
Event Property Type Status Description +
user_idStringOptional** The userId can take any string value that you specify. This will henceforth be used as a unique identifier for the user. +
+The user id parameter will remain the same throughout the lifetime of the customer & cannot be updated. It is recommended that you use your database id instead of a plain username, as database ids generally never change.
phone_numberStringMandatory**phone number of the user without the country code (we recommend that you send the Whatsapp phone number of the user, so that you can send messages to that user via interakt, else the messages won’t get sent) + +
country_codeStringMandatory**Country code of the phone number. The default value is “+91”. + +
traits ObjectOptionalUser attributes such as name, email id etc.
created_atDateOptionalTimestamp of the event in ISO-8601 format date string. If you have not passed the “createdAt” property, we will automatically use the current utc server time as the value of “createdAt” +
+ + + +**To update attributes for the above user**, the following payload could be sent in the API call: (suppose the “dob” attribute needs to be changed to “1997-12-01”). +‍ +``` +track.user( + user_id="", + country_code="+91", + phone_number="9999999999", + traits={ + “dob”: “1997-12-01” + } +) +``` +‍ +**To add a new attribute for the above user**, the following payload could be sent in the API call: (suppose the “pin code” attribute needs to be added). +‍ +``` +track.user( + user_id="", + country_code="+91", + phone_number="9999999999", + traits={ + “Pin code”: “400001” + } +) ``` +‍ +‍**Note**: + +1. In case, the above user had originally been added via the interakt dashboard (and not by calling the User Track API), then, no userId would exist for that user. In that case, you could either: +- Call the User Track API without specifying a “userId” (and only specifying the “phoneNumber” & “countryCode”), or, +- Include a userId in the API call, which will then get added for that user, and you could use that userId to reference that user in future API calls.* +‍ +2. Currently, we don’t provide the option for deleting any user / user attribute. + +**Please make sure the added userId doesn’t belong to an already existing user in your interakt account, else the API will throw an error.* + + + + + +## Event +The event track API allows customers to record user actions. Each user action (such as a new order created, new user sign up, and so on) will trigger an event to the endpoint. For example: + +**For adding a new event for a particular user**, the following payload could be sent in the API call: + +```‍ + track.event( user_id="", - event="Product Added", - traits={"price": 200}, + event="Order Placed", + “traits”={ + “orderCreatedBy”: “Gavin Roberts”, + “orderCreatedDate”: “2020-11-01T012:10:26.122Z”, + “orderNumber”: “CUS001”, + “orderValue”: “50.00” + }, country_code="+91", phone_number="9999999999", ) ``` -#### The `event` call has the following fields: - -|Field|Data type|Description| -|--|--|--| -|user_id|str or int|The ID for the user in your database.| -|event|str|Name of the event you want to track, For eg: "Product Added".| -|traits|dict|dictionary of properties for the event. If the event was **Product Added**, it might have properties like `price` or `product_name`.| -|country_code|str|Optional: Country Code of the Phone Number| -|phone_number|str|Optional: Phone number of the user (In case you don't have user_id)| + +The above API call triggers an OrderPlaced event when your user makes an order on your website/app. The API call passes the event properties orderCreatedBy, orderCreatedDate, orderNumber and orderValue to the API endpoint. +‍
+**Please note:** In case userId doesn't exist for a user, "phoneNumber" & "countryCode" would need to be specified in the above Event Track API Call. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Event Property Type Status Description +
user_idStringOptionalUnique identifier for the user.
eventStringOptionalThe action that the user has performed. It’s important to give meaningful names for your events. Example: OrderCreated, NewSignUp, OrderExecuted, etc. +
traitsObjectOptionalProperties are additional bits of information corresponding to the user action that is performed. They provide detailed information about user actions. +
created_at DateOptionalTimestamp of the event in ISO-8601 format date string. If you have not passed the “createdAt” property, we will automatically use the current utc server time as the value of “createdAt” +
phone_numberStringMandatory**phone number of the user without the country code (we recommend that you send the Whatsapp phone number of the user, so that you can send messages to that user via interakt, else the messages won’t get sent) + +
country_codeStringMandatory**Country code of the phone number. The default value is “+91”. + +
+ diff --git a/track/version.py b/track/version.py index 20709c3..0e917f6 100644 --- a/track/version.py +++ b/track/version.py @@ -1 +1 @@ -VERSION = '1.0.6' +VERSION = '1.0.7'