vivo Marketing Platform integration plan
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Ad performance data | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ |
Currently, AE supports ingesting ad performance data from the vivo Marketing Platform Marketing API, including aggregated metrics such as cost, clicks, and impressions at the ad creative level
Integration process
- Log in to the AE backend, go to the Third-party Integration module, add a vivo integration plan, complete the related configuration, and copy the authorization callback URL
- Log in to the vivo developer backend, get a developer account, create an app, and collect the required authorization information
- Go back to the AE backend, edit the vivo integration plan you created earlier to use the app's Client ID and secret, and open the authorization link to complete authorization
- Check whether the AE system receives the data successfully, and build reports
1. Plan configuration
Before ingesting data from the vivo platform, create an integration plan in the AE backend and get the authorization callback URL. Follow this document to create the integration plan
1.1 Enter temporary authorization information
First, click the Configure authorization information button in the authorization information section. In the authorization information pop-up, enter any values in the three authorization fields as temporary authorization information. You'll need to update them after you create the app on the vivo platform.
1.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull vivo Marketing API data on a schedule. You can choose to pull data for a period of time at a specific time every day. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
1.3 Receive Settings
You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.
1.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable |
| source | time_granularity | Time aggregation granularity of the data, that is, whether the pulled data is aggregated by day or by hour Valid values: DAY, HOUR |
| report_types | Data level. You can select only one data level Values: ACCOUNT (account level), CAMPAIGN (campaign level), GROUP (ad group level), ADVERTISEMENT (ad level), CREATIVE (creative level, the default level) |
1.5 Get the authorization callback URL
After completing the above configuration, click Save and authorize in the upper-right corner to get the authorization information. Copy the authorization callback URL from the first step and keep it safe. Then click Reject authorization. to close the pop-up:
The plan is saved when you click Save and authorize, so you don't need to save it separately. You have now finished the configuration in the AE backend for the time being. Next, complete the related configuration in the vivo backend.
2. Get a developer account and create an app
After creating the integration plan in the AE backend, you also need to prepare an app on the vivo developer platform. If you have already created a vivo developer app, you can skip this section
2.1 Get a developer account
Before connecting to the vivo Marketing API, you first need to get a developer account. Go to the developer website and click the Log in button in the upper-right corner to open the login page. Log in with the marketing platform account of your secondary agency account or advertiser account.
2.2 Apply for and create an app
After you log in with your marketing platform account and become a developer, go to the app management dashboard:
Click the New App button in the upper-right corner to open the app creation page:
Edit the configuration as described below, and then click Submit to create the app
-
App icon: Customizable. A 250 x 250 px app icon smaller than 50kb.
-
App name: Customizable. Up to 15 characters
-
Callback URL: Enter the callback URL you got from the vivo integration plan in the AE backend
-
App description: Describe the features your app wants to implement with the Marketing API and why these features should pass review. For example, you can explain that you need to send ad insights data back to your own analytics platform
-
Token validity period:
- Access Token validity period: How long access tokens under this app remain valid
- Refresh Token validity period: How long refresh tokens under this app remain valid. It must be longer than the access token validity period
vivo reviewers will then review the app within 2-3 business days. Continue with the next steps after the review is complete.
2.3 Get the Client ID and Client Secret
Go back to the vivo developer platform and get the clientId and Secret of the app you created on the My Apps page. These are the Client ID and Client Secret
2.4 Get the ad account ID
Finally, you also need the ID of the ad account whose data you want to pull. Log in to the vivo marketing backend and click Account Management in the menu in the upper-right corner. You can find the account ID on the account information tab in the account center section.
3. Go back to the AE backend and complete authorization
After completing the configuration in the vivo backend, go back to the AE backend, open the vivo integration plan you created earlier, and click the Configure authorization information button in the authorization information section:
Next, enter the Client ID and Client Secret you got from the vivo backend in the corresponding fields, and enter the ad account ID you got in the previous step in Advertiser ID. When you finish, click the Save button:
Then click Save and authorize in the upper-right corner to open the authorization information pop-up again. Click Go to authorization to open the authorization page of the vivo platform
If you have a vivo advertiser account, we recommend logging in with the advertiser account directly.
After completing authorization, in Authorization Information, click I have completed the above two steps in the lower-left corner, and then click Complete Authorization in the lower-right corner to finish the configuration. You have now completed the data integration for the vivo platform.
4. Data ingestion
4.1 Ingestion rules
- Because the creative report is aggregated data, we use a fixed value as the user identifier. You can think of all the data as attached to one virtual user
- The reportdate or reporttime field in the data, that is, the data aggregation time, is used as the event's #event_time
- The default event name is: vivo_ads_data
- All other fields are ingested
4.2 Included fields
The ad creative data supports pulling the following fields:
| Field name | Name and notes |
|---|---|
| campaignid | Campaign ID |
| campaignname | Campaign name |
| mediatype | Campaign type |
| groupid | Ad set ID |
| groupname | Ad group name |
| advertisementid | Ad ID |
| advertisementname | Ad name |
| creativeid | Creative ID |
| placetype | Ad placement type. For details, see Appendix - Ad placement enumeration (ad reports) |
| apppackage | Package name |
| cvtype | Conversion type. For details, see Appendix - Ad group conversion goal types |
| reportdate | Report time, returned when querying by day, in the format: 20200824 |
| reporttime | Report time, returned when querying by hour, in the format: 2020-06-28 11:00:00 |
| advertiserid | Advertiser ID |
| showcount | Impressions |
| clickcount | Clicks |
| downloadcount | Downloads |
| spent | Spend |
| activatecount | New activations |
| registercount | Game registrations |
| formsubmitcount | Form submissions |
| normalactivatecount | Standard activations |
| backactivatecount | Custom activations |
| backregistercount | Custom registrations |
| adddesktopcount | Add-to-desktop count |
| customretaincount | Custom next-day retention count |
| gamepaycount | Game payments |
| custompaycount | Custom payments |
| reactivation | Custom reactivations |
| webpay | Web purchases |
| gameappointment | Game pre-registrations |
| buttonclick | Button clicks |
| fastapppay | Quick app payments |
| personalizedevents | Personalized events |
| activatec | New activations (by billing time) |
| backactivatec | Custom activations (by billing time) |
| registerc | Game registrations (by billing time) |
| backregisterc | Custom registrations (by billing time) |
| adddesktopc | Add-to-desktop count (by billing time) |
| cdownloadcount | Downloads (by billing time) |
| customretainc | Custom next-day retention count (by billing time) |
| gamepayc | Game payments (by billing time) |
| custompayc | Custom payments (by billing time) |
| reactivationc | Custom reactivations (by billing time) |
| gameappointmentc | Game pre-registrations (by billing time) |
| firstdayrecoveryadmonetizationc | First-day revenue - ad monetization (by billing time) |
| totalrecoveryadmonetizationc | Cumulative revenue - ad monetization (by billing time) |
| firstdayrecoverypaidrechargec | First-day revenue - in-app purchases (by billing time) |
| totalrecoverypaidrechargec | Cumulative revenue - in-app purchases (by billing time) |
| cfastapppay | Quick app payments (by billing time) |
| cpersonalizedevents | Personalized events (by billing time) |
| cnormalactivatecount | Standard activations (by billing time) |
| ccreditcount | Custom credit approvals (by billing time) |
| cinstalldonecount | Completed installs (by billing time) |
| wechatgameregisterc | WeChat mini game registrations (by billing time) |
| wechatgamepayc | WeChat mini game payments (by billing time) |
| creactivationretentioncount | Custom next-day retention count of reactivated users (by billing time) |
| creditcount | Custom credit approvals (by conversion time) |
| installdonecount | Completed installs (by conversion time) |
| wechatgameregistercount | WeChat mini game registrations (by conversion time) |
| wechatgamepaycount | WeChat mini game payments (by conversion time) |
| reactivationretentioncount | Custom next-day retention count of reactivated users (by conversion time) |
| reservecount | Calendar reservations (by conversion time) |
| identifycodecount | WeChat - QR code scans |
| addwechatmpacount | WeChat - WeChat contacts added |
| dialoguempacount | WeChat - users' first messages |
| onedialoguecount | Valid inquiries |
| firstdayrecoverypaidcount | First payments on the first day in game |
| tacount | Target users (by conversion time) |
| ctacount | Target users (by billing time) |
| payonetimecount | App payments (by conversion time) |
| cpayonetimecount | App payments (by billing time) |
| payonetimeamount | App payment amount (by conversion time), in milli-cents (one-thousandth of a cent). 1 CNY = 100000 milli-cents |
| cpayonetimeamount | App payment amount (by billing time), in milli-cents (one-thousandth of a cent). 1 CNY = 100000 milli-cents |
4.3 Standardized fields
The AE system standardizes the following fields:
| Original field | Standardized field | Description |
|---|---|---|
| advertiserid | te_ads_object.ad_account_id | Ad account ID |
| campaignid | te_ads_object.campaign_id | Campaign ID |
| campaignname | te_ads_object.campaign_name | Campaign name |
| groupid | te_ads_object.ad_group_id | Ad group ID |
| groupname | te_ads_object.ad_group_name | Ad group name |
| advertisementid | te_ads_object.ad_id | Ad creative ID |
| advertisementname | te_ads_object.ad_name | Ad creative name |
| showcount | te_ads_object.impressions | Impressions |
| clickcount | te_ads_object.clicks | Clicks |
| activatecount | te_ads_object.installs | Conversions |
| spent | te_ads_object.cost | User acquisition cost |