t1-node
Node implementation of a T1 API Library. Uses Bluebird for fast, simple callback handling via promises.
Compilation/Installation
From npm
npm install @mediamath/terminalone
From source
Checkout, then npm install .
Usage
T1 Node uses dotenv for easy management of environment variables. Copy .env.template to .env and fill in your details.
To get an API key, see https://apidocs.mediamath.com
Cookie Authentication (default):
Required Env variables:
T1_API_USERNAME
T1_API_PASSWORD
T1_API_KEY
var t1 = require('@mediamath/terminalone');
var config = {
preferCookieAuth: true,
user: process.env.T1_API_USERNAME,
password: process.env.T1_API_PASSWORD,
api_key: process.env.T1_API_KEY
};
var connection = new t1.T1Connection(config);OAuth2 (Password - Resource Owner flow):
T1 Node is designed to be used for scripts. If you wish to make a UI for 3rd parties, we recommend use use the Application Code flow, which may require a little more engineering than what's covered here. Note: As of 2017-06-29 OAuth2 is not available everywhere within the MediaMath environment. Until then, for production, we recommend using the Cookie flow. This message will be updated with more services as the rollout completes.
t1conf = {
preferCookieAuth: false,
user: process.env.T1_API_USERNAME,
password: process.env.T1_API_PASSWORD,
client_id: process.env.T1_CLIENT_ID,
client_secret: process.env.T1_CLIENT_SECRET,
};
var connection = new t1.T1Connection(config);
Single Entities
Retrieve, edit and save a single entity
var agencyPromise = new t1.Entity('agency')
.get(1234, connection)
.then(function(agency) {
agency = agency;
agency.name = 'new name';
return agency.save(connection)
})
.then(function () {
console.log('saved')})
.catch(error => console.log(error));Entity Lists
Returns a generator to entities
var userParams = {
'page_limit':10
};
var that = this;
t1.EntityList.get('campaigns', connection, userParams)
.then(function(list) {
that.pg1 = list;
return t1.EntityList.getNextPage(pg1, connection)
})
.then(function(list) {
that.pg2 = list;
for (var entity of list.entities) {console.log(entity)}});
Related entities
It's possible to include related entities by including in a 'with' property in userParams.
var userParams = {
'page_limit':10,
'with':['strategies']
};
var that = this;
t1.EntityList.get('campaigns', connection, userParams).then(function(list) {
that.pg1 = list;
for (var entity of list.entities) {console.log(entity)}});Targeting
Strategy Target Segments
To get a strategy's targeting segments:
var targetingSegmentsPromise = new t1.StrategyTargetSegments()
.get(strategyId, connection)
.then(function(targetingSegments) {this.targetingSegments = targetingSegments});To edit strategy targeting segments:
targetingSegments.include = [[1, 'OR']];
targetingSegments.exclude = [[119, 'OR']];
targetingSegments.include_op = 'OR';
targetingSegments.exclude_op = 'OR';
targetingSegments.save(connection).then(function () { console.log('saved') });Strategy Target Dimensions/Values
To get a strategy's targeting values:
var targetValuesPromise = new t1.StrategyTargetValues()
.get(strategyId, connection)
.then(function(targetValues) {this.targetValues = targetValues});To edit strategy targeting segments:
targetValues.include = [[1, 'OR']];
targetValues.addTargetValues('REGN', 'INCLUDE', 'OR', [23, 251]);
targetValues.save(connection).then(function () { console.log('saved') });Strategy Audience Segments
To get a strategy's audience segments:
var audienceSegmentsPromise = new t1.StrategyAudienceegments()
.get(strategyId, connection)
.then(function(audienceSegments) {this.targetingSegments = targetingSegments});To edit strategy audience segments:
audienceSegments.include = [1405158];
audienceSegments.exclude = [1405158];
targetingSegments.include_op = 'OR';
targetingSegments.exclude_op = 'OR';
targetingSegments.save(connection).then(function () { console.log('saved') });Basic Reporting
To get a list of all reports provided by the MediaMath Reports API:
var metaReport = new t1.Report('meta');
metaReport.getMeta(conn).then(
function(report) {
console.log(report)
},
function(error) {
console.log(error.message)
});To get a report with parameters:
var performanceReport = new t1.Report('performance');
performanceReport.get(conn, {
time_window: 'yesterday',
time_rollup: 'by_day',
dimensions: 'advertiser_id',
filter: 'organization_id=???'
}).then(
function(report) {
console.log(report)
},
function(error) {
console.log(error.message)
});To get a report's metadata, which specifies fields and parameters:
performanceReport.getMeta(conn).then(
function(report) {
console.log(report)
},
function(error) {
console.log(error.message)
});Tests
npm test will run local tests.
To run integration tests, copy .env.template to .env and fill in the required values.
npm run integration will run integration tests with Mocha.
FAQ
The EntityList I requested has an empty entities object but the metadata has a nonzero count! What gives?
t1-node returns an ES6 generator for the entities property, which looks like an empty object if you inspect it in the node REPL.
You can iterate over it using for (let ... of), or simply call entities.next().value to get each entity.
Check out the Mozilla documentation for more information on iterators and generators.
There's a feature that isn't supported yet! Can you add it?
Yep! Please check the open issues to see if this is already a known problem or request. If it is, we'd love to hear your comments and ideas on how best to approach it. If not, please create an issue. Alternatively, consider contributing to the project!
I want to contribute! Is that OK?
Yes! PRs are more than welcome. Please review the contributing guidelines on how best to go about this.