Integrate Tumblr with Native API¶
This guide describes how you can integrate Tumblr Sponsored Posts with your existing Native Ad Platform API account.
The advantage for Native Ad Platform partners and developers is that you can create Tumblr posts programmatically via the Tumblr Ads API and then manage those post campaigns via the Native API.
That means, you can utilize both Tumblr and the Native API for a fully programmatic solution when you create Tumblr Sponsored Posts. You can reach Tumblr users natively with photos and videos, create interactive Call-to-action buttons, and capture the right audiences, with iOS- & Android-specific links to those audiences.
A new campaign objective for Tumblr called Social_Engagement
with CPC bidding is provided to accomplish these tasks.
Important
This guide relies on the Postman collection to test and verify the calls you make in the Native API. If you’re not familiar with Postman, which is used for building and handling HTTP requests to REST-based services, navigate to the documentation for the Postman API Toolkit in Native & Search API. You’ll need to work with global variables, which are described in the Postman Toolkit documentation.
Prerequisites¶
To work successfully with Tumblr and integrate with the Native API, do the following:
Sign up with Tumblr and create an account at
https://www.tumblr.com/register
Tumblr supports the OAuth 1.0a Protocol, so you’ll need to register your OAuth app to get your Customer Key and Secret at
https://www.tumblr.com/oauth/apps
Once these are generated, you can retrieve your Token and Token secret by clicking the Explore API at
https://api.tumblr.com/console/calls/user/info
Note
To use the Tumblr Ads API, all new apps that are created need to have their credentials whitelisted.
Postman Manage Environments¶
The simplified Postman Collection is available at
https://www.getpostman.com/collections/86a89aec765a5646f209
Use this Postman Collection, as you work through the steps in this guide, which is based off of this collection.
Note that the guide on adding global variables is available in the Postman API Toolkit.
Tumblr’s Authentication Protocols¶
The following table describes the fields required for Tumblr’s authentication protocols.
Key |
Value |
---|---|
CONSUMER_KEY |
Tumblr’s Consumer Key for authentication. |
CONSUMER_SECRET |
Tumblr’s Consumer Secret for authentication. |
TOKEN |
Tumblr’s Token for authentication. |
TOKEN_SECRET |
Tumblr’s Token Secret for authentication. |
TUMBLR_ADVERTISER_ID |
Tumblr’s Advertiser ID – Used for Tumblr Campaign Management Calls (Option A) See the Tumblr Account Management section for details on how to obtain your Advertise Id. |
BLOG_NAME |
Tumblr Blog Name without the trailing .tumblr.com |
Authorization |
Your access_token found in steps 4 and step 5 of OAuth Authentication. The token is used if you are planning on using Native & Search Campaign Management Calls (Option B) |
You can edit the Environment variables in Postman for Tumblr authentication, as shown in the Postman Manage Environments panel below:
Authenticate Tumblr Calls with OAuth 1.0a¶
The Tumblr API requires that you use the OAuth 1.0a Protocol. Once you have your Global Variables configured, select the request you are calling and do the following:
Select the Authorization tab.
In the Type dropdown, select OAuth 1.0.
Click Update Request.
The calls automatically populate with your OAuth 1.0a credentials, thus enabling you to run the call, as shown below.
Tumblr Account Management¶
This section describes the steps you need to follow if you use the Tumblr Campaign Management API.
Use this endpoint:
https://api.tumblr.com/v2/pmd/accounts
Call GET Advertiser Accounts. This will
Return an array of the current Tumblr Advertising Accounts.
Ensure your Blog displays in the
tumblelogs
array.Ensure your Native & Search Advertiser Id displays as the
yam_id
.
If you don’t see any Advertising Accounts, run the Create Advertiser Account request.
Do this: Enter your Native & Search Account ID and a nickname for the account in the body.
If you see Advertising Accounts and your Native & Search AccountID, but don’t see your blog listed under tumblelogs, do this:
Run the Add Blog to Advertiser Account.
Enter your Tumblr Advertiser ID (
id
Found in the GET call) and Tumblr Blog name directly in the Request URI.
Note
An internal Tumblr Administrator will need to approve the change.
Note
The id displayed is the TUMBLRER_ADVERTISER_ID in your global variables.
Create a Tumblr Blog Post¶
To create a new Video Post, follow these steps:
Use this endpoint:
https://api.tumblr.com/v2/blog/[BLOG_NAME without .tumblr.com]/post
For example:
https://api.tumblr.com/v2/blog/myswimmingbananacollectorfan/post
Header keypair:
Authorization - OAuth 1.0
Body keypairs:
type - video
embed - link to your video
ads_params[cta_text_code]
0 => ‘Learn more’
1 => ‘Contact us’
2 => ‘Shop now’
3 => ‘Sign up’
4 => ‘Watch more’
5 => ‘Subscribe’
6 => ‘Book now’
7 => ‘Apply now’
8 => ‘Get quote’
9 => ‘Donate now’
ads_params[cta_link_url] - where you want to link your CTA button and image to.
Other optional body keypairs:
ads_params[blogless_is_rebloggable] - 0 to disable reblogging
ads_params[blogless_is_likeable] - 0 to disable likes
ads_params[cta_android_link_url] - optional, link for Android-specific devices
ads_params[cta_ios_link_url] - optional, link for iOS-specific devices
Tags - comma-separated list
This is illustrated in the screen below:
To create a new Photo Post, follow these steps:
Create a Blog-less Photo Post with CTA with this endpoint:
https://api.tumblr.com/v2/blog/[BLOG_NAME without .tumblr.com]/post
For example:
https://api.tumblr.com/v2/blog/myswimmingbananacollectorfan/post
Header keypair:
Authorization - OAuth 1.0
Body keypairs:
type - photo
source - Photo URL
ads_params[cta_text_code]
0 => ‘Learn more’
1 => ‘Contact us’
2 => ‘Shop now’
3 => ‘Sign up’
4 => ‘Watch more’
5 => ‘Subscribe’
6 => ‘Book now’
7 => ‘Apply now’
8 => ‘Get quote’
9 => ‘Donate now’
ads_params[cta_link_url] - where you want to link your CTA button and image to.
Other optional body keypairs:
ads_params[blogless_is_rebloggable] - 0 to disable reblogging
ads_params[blogless_is_likeable] - 0 to disable likes
ads_params[cta_android_link_url] - optional, link for Android-specific devices
ads_params[cta_ios_link_url] - optional, link for iOS-specific devices
Tags - comma-separated list
This is illustrated in the screen below:
Manage Campaigns¶
To manage your campaigns, two options are available:
The Tumblr API (Option A). Note that your IP Addresses will need to be whitelisted. You’ll need to provide the range of IPs from which you’ll be sending the calls. One advantage of using this API is that ad groups are auto-generated when you create a campaign.
The Native & Search API (Option B)
Examples for both options are described in the following sections.
Option A - Use Tumblr API¶
Tumblr Campaign Management API uses a separate set of Ids from Native & Search. Ensure that you’re using the IDs generated from the Tumblr calls only.
Note
Tumblr Campaign Management calls require that your IP Addresses are whitelisted. You’ll need to provide a list of IP addresses from which you’ll be sending requests.
To create the Native & Search Campaign and AdGroup
Choose a lifetime budget with an
endDate
or a Daily budget with noendDate
.Enter your campaign details in the body.
Enter your Tumblr Advertiser Id in the URI.
The steps are illustrated in the screen below:
To create the Tumblr Ad
Take the campaign ID from your campaign creation or get campaigns call, as shown in the screen below.
Name your Ad and enter that name in the Tumblr Post URL.
Option B - Use Native API¶
The Native API calls follow the same format as the usual Native & Search Campaign Management workflow.
For example:
Create a new Native & Search campaign
Method: To create a new campaign, make a POST call to the Campaign endpoint with the required fields.
POST https://api.gemini.yahoo.com/v3/rest/campaign
{
"advertiserId":1583838,
"budget":1000,
"bid": 10,
"budgetType":"DAILY",
"campaignName":"Tumblr Test1",
"channel":"NATIVE",
"objective": "SOCIAL_ENGAGEMENT",
"status":"PAUSED"
}
Create a new Native & Search adgroup
Method: To create a new adgroup, make a POST call to the adgroup endpoint with the required fields.
POST https://api.gemini.yahoo.com/v3/rest/adgroup
{
"status": "ACTIVE",
"adGroupName": "Sample Tumblr Ad Group",
"advertiserId": 1583838,
"campaignId": 365799644,
"startDateStr": "2018-03-01",
"advancedGeoPos": "DEFAULT",
"advancedGeoNeg": "DEFAULT",
"biddingStrategy": "DEFAULT",
"ecpaGoal":null,
"bidSet": {
"bids": [
{
"priceType": "CPE",
"value": ".1",
"channel": "NATIVE"
}
]
}
}
Create a new Tumblr ad
Method: To create a new Tumblr ad, make a POST call to the ad endpoint with the required fields.
POST https://api.gemini.yahoo.com/v3/rest/ad/
{
"advertiserId": 1583838,
"campaignId": 365799644,
"adGroupId": 9689635542,
"status": "ACTIVE",
"landingUrl": "https://myswimmingbananacollectorfan.tumblr.com/post/172081051522",
"adFormat": "TUMBLR",
"title": "Tumblr Ad",
"description": "Tumblr Ad",
"displayUrl": "www.yahoo.com",
"sponsoredBy": "www.yahoo.com"
}
Use Tumblr & Native Cubes for Reporting¶
Tumblr reporting calls will display all impressions received, as well as sponsored-specific impressions.
Note
Tumblr reporting calls require that your IP Addresses are whitelisted. You’ll need to provide a list of IP addresses from which you’ll be sending requests.
To get analytics for social cubes:
Use this endpoint
https://ads-api.tumblr.com/v1/advertisers//analytics/social
The endpoint will accept JSON describing the results that you want.
To get analytics for paid cubes:
Use this endpoint
https://ads-api.tumblr.com/v1/advertisers//analytics/paid
The endpoint will accept JSON describing the results that you want.
Native Cube User Stats¶
Native cube user_stats
are described in Reporting Cubes.
All user_stats fields are supported. Tumblr-specific fields are listed below:
"field": "Reblogs"
},
{
"field": "Reblog Rate"
},
{
"field": "Likes"
},
{
"field": "Like Rate"
},
{
"field": "Follows"
},
{
"field": "Follow Rate"
},
{
"field": "Engagements"
},
{
"field": "Engagement Rate"
}
FAQs¶
Whom do I contact if I have questions or issues for support?¶
ads-API@tumblr.com cc: Native Account Team.
Can I enable Tumblr at the MDM level?¶
Currently, Tumblr can only be enabled at the Account level.
How do I create Tumblr Carousel Ads?¶
You can only create Tumblr Carousel Ads via the Tumblr UI.
My iOS and Android links are referring me back to the primary URL.¶
Make sure your links are valid iOS- and Android-specific links. Tumblr does not check if your link is in the correct format.