# Python TikTok Events API
This library is an unoffical Python wrapper arround the TikTok Events API, allowing for easy interaction with the API:
- Pydantic types are used to validate the data to be sent to TikTok.
- Customer identifiable information is hashed using SHA256 before being sent to the TikTok API.
- Events can be sent one at a time or in batches.
The TikTok Events API allows advertisers to share the actions customers take on their websites and offiline directly with TikTok. This allows advertisers to measure the effectiveness of their TikTok campaigns and optimize their ad spend.
Please reference the TikTok Events API documentation for more information on the API and the data it accepts and requires: https://ads.tiktok.com/marketing_api/docs?id=1741601162187777.
TikTok API uses custom return error codes. Reference [this TikTok Events API documentation](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097) for more information on the error codes.
## Disclaimers
1. This library is in beta. Feedback and contributions are welcome.
## Installing
You can install pytt_events_api using pip:
``` bash
pip install pytt-events-api
```
## Quick Start Guide
Here's a quick guide on how to use the library to send events to TikTok.
### Authentication
The only thing you need to do to authenticate with TikTok Events API is to set the environment variables listed below.
- `TIKTOK_ACCESS_TOKEN`: Events API access token - `Required`
- `TIKTOK_PIXEL_ID`: The ID of the pixel - `Required`
- `TIKTOK_API_VERSION`: The API version to use, defaults to `v1.3`.
- `TIKTOK_TEST_EVENT_CODE`: Used so events can be tested without affecting the pixel's data. You may find the test event code in the events manager under the "Test Events" tab.
You can find the values for these variables in the TikTok Events Manager.
The environment variables are loaded when the `TikTokAuth` class is initialized. If the environment variables are not found, the class will raise an exception.
### Importing the library and initializing the API
``` python
from pytt_events.auth import TikTokAuth
from pytt_events.tiktok_events_api import TikTokEventsApi
from pytt_events.event import Event
from pytt_events.properties import Properties
from pytt_events.context import Context, Ad, Page, User
from pytt_events.properties import ContentType
from pytt_events.properties import Content
api = TikTokEventsApi()
auth = TikTokAuth()
```
### Creating an event
``` python
context = Context(
user_agent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36',
ip='13.57.97.131',
ad=Ad(callback='E.C.P.v3fQ2RHacdkfKfofPmlyuStIIHJ4Af1tKYxF9zz2c2PLx1Oaw15oHpcfl5AH' ), # ttclid
page=Page(
url='https://www.example.com',
referrer='https://www.google.com'
),
user=User(
external_id='123456',
email='test@test.com',
phone_number='+5541998862934',
ttp='94e2a4j9-h3ss-k2h5-98cc-c84a745mk098',
))
properties = Properties(
currency='BRL', # ISO 4217
value=1.00,
description='mock description',
query='mock query',
status='mock status',
contents=[Content(
content_type=ContentType.PRODUCT,
content_id='123456789',
content_name='mock content name',
content_category='mock content category',
price=1.00,
quantity=1
)]
)
event = Event (
pixel_code=auth.TIKTOK_PIXEL_ID,
test_event_code=auth.TIKTOK_TEST_EVENT_CODE,
event='ViewContent',
event_id='123456789',
timestamp='2023-02-01T00:00:00-03:00', # str or datetime object
context=context,
properties=properties
)
```
#### Errors in the Docs
[TikTok's documentation](https://ads.tiktok.com/marketing_api/docs?id=1741601162187777) says that content_type should be a parameter of the Properties object, but it actually is a parameter of the Content object.
### Sending an event
``` python
response = api.post_event(
event=event,
auth=auth
)
```
### Sending events in bulk
``` python
events = []
response = api.post_events_in_bulk(events=events, auth=auth)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "pytt-events-api",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python,tiktok,events,api,tiktok ads,tiktok events api",
"author": "Victor Valar",
"author_email": "<valar@victorvalar.me>",
"download_url": "https://files.pythonhosted.org/packages/25/3c/90c0f471574ea0e000a9e1f649cc2a785e90bcff259d4cbb47850a0a0f7c/pytt_events_api-0.1.10.tar.gz",
"platform": null,
"description": "\n# Python TikTok Events API\n\nThis library is an unoffical Python wrapper arround the TikTok Events API, allowing for easy interaction with the API:\n- Pydantic types are used to validate the data to be sent to TikTok.\n- Customer identifiable information is hashed using SHA256 before being sent to the TikTok API.\n- Events can be sent one at a time or in batches.\n\nThe TikTok Events API allows advertisers to share the actions customers take on their websites and offiline directly with TikTok. This allows advertisers to measure the effectiveness of their TikTok campaigns and optimize their ad spend.\n\nPlease reference the TikTok Events API documentation for more information on the API and the data it accepts and requires: https://ads.tiktok.com/marketing_api/docs?id=1741601162187777.\n\nTikTok API uses custom return error codes. Reference [this TikTok Events API documentation](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097) for more information on the error codes.\n## Disclaimers\n1. This library is in beta. Feedback and contributions are welcome.\n\n## Installing\nYou can install pytt_events_api using pip:\n``` bash\npip install pytt-events-api\n```\n\n## Quick Start Guide\nHere's a quick guide on how to use the library to send events to TikTok.\n### Authentication\nThe only thing you need to do to authenticate with TikTok Events API is to set the environment variables listed below.\n- `TIKTOK_ACCESS_TOKEN`: Events API access token - `Required`\n- `TIKTOK_PIXEL_ID`: The ID of the pixel - `Required`\n- `TIKTOK_API_VERSION`: The API version to use, defaults to `v1.3`.\n- `TIKTOK_TEST_EVENT_CODE`: Used so events can be tested without affecting the pixel's data. You may find the test event code in the events manager under the \"Test Events\" tab.\n\nYou can find the values for these variables in the TikTok Events Manager.\n\nThe environment variables are loaded when the `TikTokAuth` class is initialized. If the environment variables are not found, the class will raise an exception.\n### Importing the library and initializing the API\n``` python\nfrom pytt_events.auth import TikTokAuth\nfrom pytt_events.tiktok_events_api import TikTokEventsApi\nfrom pytt_events.event import Event\nfrom pytt_events.properties import Properties\nfrom pytt_events.context import Context, Ad, Page, User\nfrom pytt_events.properties import ContentType\nfrom pytt_events.properties import Content\n\napi = TikTokEventsApi()\nauth = TikTokAuth()\n```\n\n### Creating an event\n``` python\ncontext = Context(\n user_agent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36',\n ip='13.57.97.131',\n ad=Ad(callback='E.C.P.v3fQ2RHacdkfKfofPmlyuStIIHJ4Af1tKYxF9zz2c2PLx1Oaw15oHpcfl5AH' ), # ttclid\n page=Page(\n url='https://www.example.com',\n referrer='https://www.google.com'\n ),\n user=User(\n external_id='123456',\n email='test@test.com',\n phone_number='+5541998862934',\n ttp='94e2a4j9-h3ss-k2h5-98cc-c84a745mk098',\n ))\nproperties = Properties(\n currency='BRL', # ISO 4217\n value=1.00,\n description='mock description',\n query='mock query',\n status='mock status',\n contents=[Content(\n content_type=ContentType.PRODUCT,\n content_id='123456789',\n content_name='mock content name',\n content_category='mock content category',\n price=1.00,\n quantity=1\n )]\n)\nevent = Event (\n pixel_code=auth.TIKTOK_PIXEL_ID,\n test_event_code=auth.TIKTOK_TEST_EVENT_CODE,\n event='ViewContent',\n event_id='123456789',\n timestamp='2023-02-01T00:00:00-03:00', # str or datetime object\n context=context,\n properties=properties\n)\n```\n\n#### Errors in the Docs\n[TikTok's documentation](https://ads.tiktok.com/marketing_api/docs?id=1741601162187777) says that content_type should be a parameter of the Properties object, but it actually is a parameter of the Content object.\n\n### Sending an event\n``` python\nresponse = api.post_event(\n event=event,\n auth=auth\n)\n```\n\n### Sending events in bulk\n``` python\nevents = []\nresponse = api.post_events_in_bulk(events=events, auth=auth)\n```\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "LICENSE.txt",
"summary": "Python wrapper for the TikTok Events API",
"version": "0.1.10",
"project_urls": null,
"split_keywords": [
"python",
"tiktok",
"events",
"api",
"tiktok ads",
"tiktok events api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3eaf988cb4307b6e0d557631ffc5a63f32396ee3d7f3250fffab808f30a2b327",
"md5": "8d3d216b3e816806ebe90bebfcd1c6d8",
"sha256": "3c582d818edd2d0aa1af487be17fb22252c47aca450da8c9334eab893bd1a79f"
},
"downloads": -1,
"filename": "pytt_events_api-0.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d3d216b3e816806ebe90bebfcd1c6d8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14120,
"upload_time": "2023-09-14T19:38:24",
"upload_time_iso_8601": "2023-09-14T19:38:24.871264Z",
"url": "https://files.pythonhosted.org/packages/3e/af/988cb4307b6e0d557631ffc5a63f32396ee3d7f3250fffab808f30a2b327/pytt_events_api-0.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "253c90c0f471574ea0e000a9e1f649cc2a785e90bcff259d4cbb47850a0a0f7c",
"md5": "98bc416ecbcd6e3b5b1ca4c2c50b49b2",
"sha256": "adaeb897f0c002e4fe1b252866e4b789279dac080097016aeda851bc477c5a1b"
},
"downloads": -1,
"filename": "pytt_events_api-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "98bc416ecbcd6e3b5b1ca4c2c50b49b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12164,
"upload_time": "2023-09-14T19:38:26",
"upload_time_iso_8601": "2023-09-14T19:38:26.220083Z",
"url": "https://files.pythonhosted.org/packages/25/3c/90c0f471574ea0e000a9e1f649cc2a785e90bcff259d4cbb47850a0a0f7c/pytt_events_api-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-14 19:38:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pytt-events-api"
}
JSON