tap_tiktok_ads

This is a Singer tap that produces JSON-formatted data from the TikTok Marketing API following the Singer spec.

This tap:

• Pulls raw data from the TikTok Marketing API.
• Extracts the following resources from TikTok Marketing API for a single repository:
  • Accounts - Endpoint: https://business-api.tiktok.com/open_api/v1.2/advertiser/info/
  • Campaigns - Endpoint: https://ads.tiktok.com/open_api/v1.2/campaign/get/
  • Adgroups - Endpoint: https://ads.tiktok.com/open_api/v1.2/adgroup/get/
  • Ads - Endpoint: https://business-api.tiktok.com/open_api/v1.2/ad/get/
  • Reporting - Endpoint: https://ads.tiktok.com/open_api/v1.2/reports/integrated/get/
    • Ad Insights
    • Ad Insights by Age and Gender
    • Ad Insights by Country
    • Ad Insights by Platform
• Outputs the schema for each resource
• Incrementally pulls data based on the input state

Authentication

The tap uses an access token provided by the TikTok Marketing API to make the calls to the API. The access token does not expire, but it'll become invalid if the advertiser cancels the authorization. An invalid access token cannot be renewed or refreshed. THis access token can be obtained by following the step-by-step instructions on the TikTok Marketing API Docs - Authorization and TikTok Marketing API Docs - Authentication.

Config File

The tap requires some fields to be completed in a config file in order to work. Currently the tap supports the fields: - start_date: Date from which the tap starts extracting data. RFC3339 format. - end_date: Date from which the tap ends extracting data. RFC3339 format. (Optional) - user_agent: User agent that makes the API call. - access_token: Access token for the TikTok Marketing API - accounts: A list of account ids.

{
  "start_date": "2019-01-01T00:00:00Z",
  "end_date": "2020-01-01T00:00:00Z",
  "user_agent": "tap-tiktok-ads <api_user_email@your_company.com>",
  "access_token": "YOUR_ACCESS_TOKEN",
  "accounts": []
}

Install

Clone this repository, and then install using setup.py. We recommend using a virtualenv:

    > virtualenv -p python3 venv
    > source venv/bin/activate
    > python setup.py install
    OR
    > cd .../tap-tiktok-ads
    > pip install .

Dependent libraries

The following dependent libraries were installed.

    > pip install singer-python
    > pip install singer-tools
    > pip install target-stitch
    > pip install target-json

Setup

Create your tap's config.json file which should look like the following:

```json
{
    "start_date": "2019-01-01T00:00:00Z",
    "user_agent": "tap-tiktok-ads <api_user_email@your_company.com>",
    "access_token": "YOUR_ACCESS_TOKEN",
    "accounts": [id1, id2, id3]
}
```

Optionally, also create a `state.json` file. `currently_syncing` is an optional attribute used for identifying the last object to be synced in case the job is interrupted mid-stream. The next run would begin where the last job left off.

```json
{
    "currently_syncing": "ad_insights",
    "bookmarks": {
        "accounts": "2020-04-06 10:52:54.000000Z",
        "campaigns": "2021-08-10T06:56:51.000000Z",
        "adgroups": "2021-08-10T06:56:51.000000Z",
        "ads": "2021-08-09T09:11:54.000000Z",
        "ad_insights": "2021-08-18T00:00:00.000000Z",
        "ad_insights_by_age_and_gender": "2021-08-18T00:00:00.000000Z",
        "ad_insights_by_country": "2021-08-18T00:00:00.000000Z",
        "ad_insights_by_platform": "2021-08-18T00:00:00.000000Z"
    }
}
```

Discovery Mode

Run the Tap in Discovery Mode. This creates a catalog.json for selecting objects/fields to integrate:

> tap-tiktok-ads --config config.json --discover > catalog.json

See the Singer docs on discovery mode here.

Sync Mode

Run the Tap in Sync Mode (with catalog) and write out to state file

For Sync mode:

> tap-tiktok-ads --config tap_config.json --catalog catalog.json > state.json
> tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

To load to json files to verify outputs:

> tap-tiktok-ads --config tap_config.json --catalog catalog.json | target-json > state.json
> tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

To pseudo-load to Stitch Import API with dry run:

> tap-tiktok-ads --config tap_config.json --catalog catalog.json | target-stitch --config target_config.json --dry-run > state.json
> tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

Test the Tap

While developing the Linkedin Ads tap, the following utilities were run in accordance with Singer.io best practices: Pylint to improve code quality

> pylint tap_<tap_name> --disable 'broad-except,chained-comparison,empty-docstring,fixme,invalid-name,line-too-long,missing-class-docstring,missing-function-docstring,missing-module-docstring,no-else-raise,no-else-return,too-few-public-methods,too-many-argument

Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

To check the tap and verify working:

> tap-tiktok-ads --config tap_config.json --catalog catalog.json | singer-check-tap > state.json
> tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

Check tap resulted in the following:

The output is valid.
It contained 12135 messages for 8 streams.

      8 schema messages
  11593 record messages
    534 state messages

Details by stream:
+-------------------------------+---------+---------+
| stream                        | records | schemas |
+-------------------------------+---------+---------+
| advertisers                   | 1       | 1       |
| campaigns                     | 23      | 1       |
| adgroups                      | 29      | 1       |
| ads                           | 67      | 1       |
| ad_insights                   | 955     | 1       |
| ad_insights_by_age_and_gender | 6908    | 1       |
| ad_insights_by_country        | 1415    | 1       |
| ad_insights_by_platform       | 2195    | 1       |
+-------------------------------+---------+---------+

---

Copyright © 2021 Stitch