TikTok Business API Ruby Gem
A Ruby interface to the TikTok Business API with support for campaigns, ad groups, ads, and more.
Installation
Add this line to your application's Gemfile:
gem 'tiktok_business_api'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install tiktok_business_api
Getting Started
Configuration
You need to configure the client with your TikTok app credentials:
TiktokBusinessApi.configure do |config|
config.app_id = 'your_app_id'
config.secret = 'your_app_secret'
config.debug = true # Enable request/response logging
end
If you want to use a custom logger:
require 'logger'
logger = Logger.new(STDOUT)
logger.level = Logger::DEBUG
TiktokBusinessApi.configure do |config|
config.logger = logger
end
Authentication
Generate an authorization URL
client = TiktokBusinessApi.client
auth_url = client.auth.('https://your-redirect-url.com/callback')
After the user authorizes your app, TikTok will redirect to your callback URL with an authorization code.
Generate an access token
auth_code = 'auth_code_from_callback'
redirect_uri = 'https://your-redirect-url.com/callback'
response = client.auth.generate_access_token(auth_code, redirect_uri)
access_token = response['data']['access_token']
The access token will automatically be stored in your client configuration for future requests.
Working with Campaigns
# Create a new client instance
client = TiktokBusinessApi.client(access_token: 'your_access_token')
# Create a campaign
advertiser_id = '6000000000000'
campaign_params = {
campaign_name: 'My First Campaign',
objective_type: 'TRAFFIC',
budget_mode: 'BUDGET_MODE_TOTAL',
budget: 1000
}
campaign = client.campaigns.create(advertiser_id, campaign_params)
campaign_id = campaign['campaign_id']
# Get a list of campaigns
campaigns = client.campaigns.list(advertiser_id)
# Get a specific campaign
campaign = client.campaigns.get(advertiser_id, campaign_id)
# Update a campaign
update_params = {
campaign_name: 'Updated Campaign Name'
}
client.campaigns.update(advertiser_id, campaign_id, update_params)
# Enable/disable a campaign
client.campaigns.update_status(advertiser_id, campaign_id, 'DISABLE')
# Delete a campaign
client.campaigns.delete(advertiser_id, campaign_id)
# List all campaigns with pagination (yields each campaign to a block)
client.campaigns.list_all(advertiser_id) do |campaign|
puts "Campaign: #{campaign['campaign_name']}"
end
Working with Identities
The Identity feature allows you to create Spark Ads by working with authorized TikTok accounts.
# List available identities
identities = client.identities.list(advertiser_id: 'your_advertiser_id')
# Get information about a specific identity
identity_info = client.identities.get_info(
advertiser_id: 'your_advertiser_id',
identity_id: 'identity_id',
identity_type: 'TT_USER'
)
# Create a custom user identity
new_identity = client.identities.create(
advertiser_id: 'your_advertiser_id',
display_name: 'My Custom Identity',
image_uri: 'image_id_from_uploaded_image' # Optional
)
# List all identities with pagination
client.identities.list_all(advertiser_id: 'your_advertiser_id') do |identity|
puts "Identity: #{identity['display_name']} (#{identity['identity_type']})"
end
Working with Images
Upload and manage images for your ads:
# Upload an image file
uploaded_image = client.images.upload(
advertiser_id: 'your_advertiser_id',
image_file: File.open('/path/to/image.jpg')
)
# Get image info
image_info = client.images.get_info('your_advertiser_id', uploaded_image['image_id'])
# Search for images
images = client.images.search(
advertiser_id: 'your_advertiser_id',
page: 1,
page_size: 20
)
Logging Requests and Responses
You can enable debug logging to see all API requests and responses:
TiktokBusinessApi.configure do |config|
config.debug = true
config.logger = Logger.new(STDOUT)
end
Error Handling
The gem raises specific exceptions for different error types:
begin
client.campaigns.create(advertiser_id, campaign_params)
rescue TiktokBusinessApi::AuthenticationError => e
puts "Authentication failed: #{e.}"
rescue TiktokBusinessApi::RateLimitError => e
puts "Rate limit exceeded: #{e.}"
rescue TiktokBusinessApi::ApiError => e
puts "API error: #{e.}, Status code: #{e.status_code}, Body: #{e.body}"
rescue TiktokBusinessApi::Error => e
puts "General error: #{e.}"
end
Development
With Docker (recommended)
This gem includes a Docker-based development environment to ensure consistent development and testing.
Prerequisites
- Docker and Docker Compose
- Make (optional, but recommended)
Setup using Make
# Set up the development environment
make setup
# Run tests
make test
# Open a shell in the Docker container
make shell
# Start a console with the gem loaded
make console
# Run RuboCop linting
make lint
# Generate documentation
make docs
# Build the gem
make build
# Prepare a new release
make release
# Publish to RubyGems
make publish
# View all available commands
make help
Without Make
If you prefer to use Docker Compose directly:
# Set up the development environment
docker-compose build
# Run tests
docker-compose run --rm test
# Start a console with the gem loaded
docker-compose run --rm console
# Open a shell in the Docker container
docker-compose run --rm gem bash
Without Docker
If you prefer to develop without Docker:
# Install dependencies
bundle install
# Run tests
bundle exec rake spec
# Run linting
bundle exec rubocop
# Generate documentation
bundle exec yard
# Build the gem
bundle exec rake build
# Start a console with the gem loaded
bin/console
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
License
The gem is available as open source under the terms of the MIT License.