Taobao Advertising Integration
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document describes the Taobao advertising platform integration built around the TaoXi (Universal Merchant Platform) API. It covers campaign management, ad group configuration, and creative asset handling, along with advertising performance metrics synchronization, budget allocation, and targeting parameters. The integration supports real-time and historical reporting, bid word management, and audience targeting configuration. Authentication leverages Taobao Open Platform OAuth and API key management. Reporting capabilities include campaign performance, ad group analytics, and creative effectiveness tracking. The document also outlines data transformation processes from the advertising platform APIs to internal analytics models, budget optimization strategies, performance monitoring, API rate limiting, error handling, and retry mechanisms.
Project Structure
The TaoXi integration is organized as a Kratos microservice with clear separation of concerns:
- API definitions: Protocol Buffers define the TaoXi service contract, including campaign, ad group, creative, bid word, and report messages.
- Service layer: Implements the TaoxiService gRPC/HTTP handlers and translates between API and business models.
- Business logic: Encapsulates use cases and orchestrates repository calls.
- Data layer: Provides a TaobaoClient for authenticating and invoking Taobao Open Platform endpoints.
- Configuration: Nacos-backed runtime configuration for server, logging, and Taobao credentials.
- OpenAPI: Exposes REST endpoints via gRPC-Gateway for human-friendly access.
Diagram sources
Section sources
Core Components
- TaoxiService: Implements all RPC endpoints defined in the TaoXi service, converting between protobuf messages and internal business models.
- Business Usecases: Encapsulate domain logic for campaigns, ad groups, bid words, creatives, and reports.
- TaobaoClient: Handles authentication, request signing, and response parsing for Taobao Open Platform.
- Repository Interface: Defines data access contracts for all TaoXi entities and operations.
- Configuration: Loads server, logging, and Taobao credentials from Nacos.
Key responsibilities:
- Campaign Management: List/find, get details, batch budget/bid updates, partial updates, deletion, and campaign group operations.
- Ad Group Management: Horizontal pagination, batch add, partial updates, batch bid updates, and deletion.
- Bid Word Management: List, add, update, delete, KR suggestions, and quality score retrieval.
- Creative Management: Horizontal pagination, add/update, bind/unbind, and preview.
- Reporting: Realtime, account, campaign, ad group, bid word, crowd, creative, area, and charge sum reports.
- Account Utilities: Balance, available marketing scenarios, universal user check, material items, bid/budget suggestions.
Section sources
Architecture Overview
The service exposes both gRPC and HTTP endpoints. gRPC-Gateway translates HTTP JSON requests to gRPC calls. The service delegates business logic to use cases and repositories, which interact with the Taobao Open Platform via the TaobaoClient. Configuration is managed centrally via Nacos.
Diagram sources
Detailed Component Analysis
Campaign Management
Endpoints support listing campaigns (with pagination and filters), retrieving details, batch budget/bid updates, partial field updates, and deletion. Campaign groups can be listed, created, and modified.
Implementation highlights:
- Request conversion: API request messages are mapped to internal usecase requests.
- Response conversion: Internal domain models are transformed to protobuf responses.
- Batch operations: Results include success/failure counts and messages.
Diagram sources
Section sources
Ad Group Configuration
Ad groups can be queried horizontally with pagination, added in batches, partially updated, batch bid updated, and deleted.
Key points:
- Horizontal pagination supports filtering by campaign IDs, statuses, and ad group name.
- Batch add accepts campaign ID, ad group name, promotion ID, and bid.
- Partial updates allow changing name, status, and bid.
Section sources
Creative Asset Handling
Creative management includes horizontal pagination, adding/updating creatives, binding/unbinding to campaigns/ad groups, and preview URL retrieval. Creative requirements (dimensions, formats, sizes) can be queried per business code and creative type.
Transformation:
- CreativeInfo domain model is mapped to/from protobuf messages.
- Bind/Unbind operations link creatives to specific campaigns and ad groups.
Section sources
Bid Word Management
Bid words support listing, adding, updating, deleting, KR suggestions, and quality score retrieval. Requests include match types and status controls.
Section sources
Reporting Capabilities
The service provides comprehensive reporting across multiple dimensions:
- Realtime report: Hourly and date-level metrics with configurable aggregation domains and fields.
- Account/Campaign/Adgroup/Bidword/Crowd/Creative/Area reports: Historical metrics with optional pagination.
- Charge sum: Total spending over a period.
- Async download: Task-based asynchronous report generation and retrieval.
Metrics covered:
- Spend, impressions, clicks, click-through rate, cost-per-click, cost-per-thousand impressions, return on investment, conversion rate, transaction amounts and counts, cart additions, favorites, in-store visits and visitors, membership acquisition, new customer conversions, and total conversions.
Section sources
Data Synchronization Patterns
Data synchronization follows a consistent pattern:
- Request parsing: API request messages are converted to internal usecase requests.
- Repository invocation: Usecases call repository methods to fetch or mutate data.
- Response shaping: Internal domain models are transformed to protobuf responses.
- Error propagation: Errors are returned upstream with appropriate context.
Diagram sources
Budget Allocation and Targeting Parameters
- Budget allocation: Batch update campaign budgets and ad group bids via dedicated endpoints.
- Targeting parameters: Campaigns include marketing scenario codes, optimization targets, scheduling, and geographic targeting. Reports support segmentation by campaign/date and other domains.
Section sources
Authentication Flow and API Key Management
Authentication leverages Taobao Open Platform OAuth and HMAC signing:
- Session-based authentication: Sessions are passed to TaobaoClient for authorized requests.
- HMAC signature: All requests are signed using HMAC-MD5 with sorted parameters and app secret.
- Service context: Requests include a service context with marketing scenario code, member ID, and ext fields.
Diagram sources
Section sources
Examples
Campaign Creation
- Use the campaign add operation to create new campaigns with specified marketing scenario, budget, bid, and targeting parameters.
- Retrieve campaign details via get campaign endpoint.
Section sources
Bid Word Management
- Add keywords to campaigns/ad groups with match types and bids.
- Update bids and match types in bulk.
- Retrieve quality scores and KR suggestions.
Section sources
Audience Targeting Configuration
- Query recommended audiences and manage crowd lists.
- Use crowd reports to analyze performance by audience segments.
Section sources
Data Transformation Processes
The service converts between Taobao Open Platform responses and internal analytics models:
- Response parsing: Generic ParseResponse function extracts top_result.info and top_result.data.
- Metric mapping: ReportIndex fields are mapped to standardized metric names for analytics consumption.
Section sources
Budget Optimization Strategies and Performance Monitoring
- Monitor spend and conversion metrics via campaign/ad group reports.
- Adjust bids and budgets based on ROI and CVR thresholds.
- Use quality score insights for bid word optimization.
- Track performance by date/hour to identify optimal scheduling windows.
Section sources
API Rate Limiting, Error Handling, and Retry Mechanisms
- HTTP client timeout: Requests are made with a 30-second timeout.
- Error response parsing: Taobao error responses are parsed and surfaced as structured errors.
- Retry strategy: Not implemented in the current client; consider implementing exponential backoff with jitter for transient failures.
- Circuit breaker: Not implemented; consider integrating a circuit breaker pattern for downstream resilience.
Section sources
Dependency Analysis
The service follows layered architecture with clear interfaces:
- API layer depends on protobuf definitions.
- Service layer depends on business usecases.
- Business layer depends on repository interface.
- Repository implementation depends on TaobaoClient.
- Configuration is injected via Nacos.
Diagram sources
Section sources
Performance Considerations
- Pagination: Use offset/page_size parameters to limit response sizes for reporting endpoints.
- Filtering: Apply biz_code_in_list, campaign/adgroup filters to reduce dataset volume.
- Asynchronous downloads: Use async report download tasks for large datasets.
- Client timeouts: Respect HTTP client timeouts to prevent long-hanging requests.
Troubleshooting Guide
Common issues and resolutions:
- Authentication failures: Verify app_key/app_secret and session validity.
- Signature errors: Ensure parameter sorting and HMAC computation are correct.
- Response parsing errors: Confirm response keys and top_result structure.
- Timeout errors: Increase HTTP client timeout or reduce query scope.
Section sources
Conclusion
The TaoXi integration provides a robust foundation for managing Taobao advertising campaigns, ad groups, and creatives while delivering comprehensive reporting and analytics. The layered architecture enables maintainable extensions for additional features, improved error handling, and enhanced performance monitoring. Future enhancements could include built-in retry/backoff, circuit breakers, and expanded reporting dimensions.