t1-java

Java SDK for MediaMath Platform APIs

Maven Integration

You can integrate the latest t1-java build easily by just including the following lines in your pom.xml.

<dependencies>
  <dependency>
       <groupId>com.mediamath</groupId>
       <artifactId>t1-java</artifactId>
       <version>1.2.1</version>
   </dependency>
</dependencies>

You can also download the latest jar from Maven Central or from the following source - https://oss.sonatype.org/content/repositories/releases/com/mediamath/t1-java/1.2.1/

#Build project from source

For developer build

mvn clean install -Pdev
For Production build

mvn clean install -Pprod

Usage

make sure the build path entries in your project are pointing to the jar file created.

Authentication - Cookie Auth (default)

using constructor

  TerminalOne one = new TerminalOne(username, password, key);

using authenticate method

  TerminalOne one = new TerminalOne();
  one.authenticate(username, password, key);

OAuth2 (Password - Resource Owner flow):

T1 Java 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.

	TerminalOne one = new TerminalOne();
	one.authenticate(username, password, clientId, clientSecret);

Fetching Entities and Collections

Using get method of TerminalOne we can fetch entities and collections.

	TerminalOne one = new TerminalOne();
	one.get(QueryCriteria query)

Returns: If single entity is specified, returns a single entity object. If multiple entities, generator yielding each entity.

QueryCriteria class has parameters as below:

collection: T1 collection i.e. entity to fetch, like "advertisers","campaigns"
```
 Example: query.setCollection("campaigns");
```
entity: Integer ID of entity being retrieved from T1
```
 Example: query.setEntity(12312);
```
child: Child object of a particular entity, e.g. "dma", "acl","margins"
```
 Example: query.setChild("browser");
```

sortBy: sort order. Default "id". e.g. "-id", "name"

 Example: query.setSortBy("id"); //ascending
 		 query.setSortBy("-id"); //descending

parent: Integer ID of entity. When set, it returns entities with this parent id.
```
 Example: query.setParent(Long.valueOf(111555)); //requires long value
```

limit: to query the entity. Its a Map of name-value pair of size 1.

 Example: Map<String, Long> limitMap = new HashMap<String, Long>();
 		 limitMap.put("agency", Long.valueOf(111555));
 		 query.setLimit(limitMap);

full: When retrieving multiple entities, specifies which types to return the full record. It can accept values as boolean(true/false), String or List of Strings.

 Example: 1. As Boolean
 			FullParamValues fullParamvalue = new FullParamValues();
 			fullParamvalue.setBoolValue(true);	
 		 	query.setFull(fullParamvalue);
 	
 		 2. As String
 		 	FullParamValues fullParamvalue = new FullParamValues();
 			fullParamvalue.setStrValue("agency"); 
 			query.setFull(new FullParamValues().setStrValue("agency"))

 		 3. As List of Strings
 			List<String> fullList = new ArrayList<String>();
 			fullList.add("campaign");
 			fullList.add("advertiser");
 			FullParamValues fullParamvalue = new FullParamValues();
 			fullParamvalue.setListValue(fullList)
 			query.setFull(fullParamvalue)

pageLimit and pageOffset: handles pagination.

pageLimit specifies how many entities to return at a time, default and max of 100.

pageOffset specifies which entity to start at for that page.
```
  Example: query.setPageLimit(10);
  		 query.setPageLimit(10).setPageOffset(200);
```
getAll: Boolean(true/false) whether to retrieve all results for a query or just a single page. Mutually exclusive with pageLimit/pageOffset.
```
  Example:query.setGetAll(true);
```

include: String/List of relations to include in query.

 Example: 1. As String
 			query.setInclude(new ConditionQuery("agency"));	
 		 2. As List of lateral (non-hierarchical) relations
 		    query.setInclude(new ConditionQuery("agency","organization"));
 		 3.As List of list/strings of hierarchical relations
 			query.setInclude(new ConditionQuery("ad_server"))
 				 .setInclude(new ConditionQuery("vertical"))

creativeType: String(video/normal) Specifies which type of creative to fetch. Use "video" while fetching video creatives and "normal" for other types of creatives.
```
 Example: query.setCreativeType(CreativeType.video);
```

downloadSiteList: Boolean(true/false) when true, performs the retrieval of the sites defined within the site_list. default value is false.

  Example:
  QueryCriteria query = QueryCriteria.builder().setCollection("site_lists").setEntity(12345)
  		.setDownloadSiteList(true).build();

  BufferedReader reader = null;

  try {
  	reader = terminalOne.getSiteListData(query);
  } catch (ClientException | ParseException e) {
  	// TODO Auto-generated catch block
  	e.printStackTrace();
  }

Following methods of TerminalOne class is used to fetch sitelist.

terminalOne.getSiteListData(query);

Method returns BufferedReader object.

query: String search parameters. Invoked by find.

 Example: query.setQuery("agency_id%3E=109308");

We can use different combinations of these parameters to extract expected result. Here are some complete examples.

	    TerminalOne one = new TerminalOne();

		QueryCriteria query = QueryCriteria.builder()
								.setCollection("advertisers")		//collection
								.setEntity(154161)		//entity
								.build();			
		JsonResponse<?> jsonresponse = one.get(query);
		------------------------------------------------------------
		QueryCriteria query = QueryCriteria.builder()
								.setCollection("advertisers")
								.setEntity(154161)
								.setInclude(new ConditionQuery("agency", "organization"))  		
								.build();
		JsonResponse<?> jsonresponse = one.get(query);
		------------------------------------------------------------
		QueryCriteria query = QueryCriteria.builder()
								.setCollection("advertisers")
								.setPageLimit(40)		//pageLimit
								.setPageOffset(100)		//pageOffset
								.build();
		JsonResponse<?> jsonresponse = one.get(query);
		------------------------------------------------------------
		Map<String, Long> limitList = new HashMap<String, Long>();
		limitList.put("agency", Long.valueOf(111555));
		QueryCriteria query = QueryCriteria.builder()
								.setCollection("advertisers")		 
								.setLimit(limitList)		//limit
								.setGetAll(true)		//getAll
								.setSortBy("-updated_on")
								.build();
		JsonResponse<?> jsonresponse = one.get(query);
		------------------------------------------------------------
		QueryCriteria query = QueryCriteria.builder()
								.setCollection("strategies")
								.setEntity(1376198)
								.setChild("browser")
								.setPageLimit(1)
								.build();

Searching for entities

Limiting entities by relation ID is one way to limit entities, but we can also search with more intricate queries using find:

	TerminalOne one = new TerminalOne();
	one.find(QueryCriteria query);

Here QueryCriteria has 3 parameters

queryParamName: String query parameter name
queryOperator: arithmetic operator like < > = !=.

It handled by Fileters object constants-
- IN
- NULL
- NOT_NULL
- EQUALS
- NOT_EQUALS
- GREATER
- GREATER_OR_EQUAL
- LESS
- LESS_OR_EQUAL
- CASE_INS_STRING

queryParams : values to pass to queryParameter. It can be Boolean, String, Number or any List

 Example: 1. queryParam As Number   
 		QueryCriteria query = QueryCriteria.builder()
 							.setCollection("advertisers")
 							.setQueryParamName("agency_id")
 							.setQueryOperator(Filters.GREATER_OR_EQUAL)
 							.setQueryParams(new QueryParamValues(109308))
 							.setPageLimit(100)
 							.build();
 		JsonResponse<?> jsonresponse = one.find(query);

 		2. queryParam as String
 		QueryCriteria query = QueryCriteria.builder()
 							.setCollection("advertisers")
 							.setQueryParamName("name")
 							.setQueryOperator(Filters.EQUALS)
 							.setQueryParams(new QueryParamValues("Retirement"))
 							.setPageLimit(100)
 							.build();
 		JsonResponse<?> jsonresponse = one.find(query);

 		3. queryParam as List, to be used as IN query
 		//form list
 		List<Object> inQueryParams = new ArrayList<Object>();
 		inQueryParams.add(154121);
 		inQueryParams.add(153226);
 		inQueryParams.add(150994);
 		QueryCriteria query = QueryCriteria.builder()
 							.setCollection("advertisers")
 							.setQueryParams(new QueryParamValues("name"))
 							.setQueryOperator(Filters.IN)
 							.setQueryParams(new QueryParamValues(inQueryParams))
 							.setPageLimit(100)
 							.build();
 		JsonResponse<?> jsonresponse = one.find(query);

TerminalOne.find(QueryCriteria q) method can be used as a helper method to TerminalOne.get(QueryCriteria q) method and all get related QueryCriteria parameters can be used along with find() parameters.

How to Post

you need to import the Entities from the package com.mediamath.terminalone.models.*;

Example
```
TerminalOne one = new TerminalOne();
one.authenticate("someUser", "somepwd", "somekey");

Agency agency = new Agency();
agency.setName("testAgency");
agency.setOrganizationId(10001);

agency = one.save(agency);
```
The above snippet of code sets the agency entity attributes and saves it with the save method of TerminalOne

The save method is overloaded, accepting different Entities as parameters. Entities are derived from T1Entity which serves as a base interface for all the entities.

The save method throws ClientException or ParseException or IOException in case of any error occurs.

The return type of the save method can be the same Type of Entity as passed into the argument OR it will be a null or in some special cases it will be JsonResponse<? extends T1Entity>

Video Creatives

uploading a video creative is broken down into two steps.

first call creates a video creative and it returns a creative id.
second call uploads the file using the creative id received from the first step.
Before Second call, we need to get Key and Uploader host by calling GET https://{HOST}/{API_BASE}/creatives/{creative Id}/upload

first call requires a VideoCreative entity as an input param.

####### Example

  TerminalOne t1 = new TerminalOne(user, password,production_key);

  VideoCreative videoCreative = new VideoCreative();
  videoCreative.setName("videoCreative2");
  videoCreative.setStartTime(1468486396); //unix timestamp
  videoCreative.setLandingUrl("http://www.somedomain.com");
  videoCreative.setAdvertiser(122631);
  videoCreative.setEndTime(1470009600); //unix timestamp
  videoCreative.setConcept(847527);
  videoCreative.setClickthroughUrl("http://www.somedomain.com");
  //set event pixels
  List<EventPixel> eventPixels = new ArrayList<EventPixel>();
	eventPixels.add(new EventPixel(EventPixelsEnum.ImpSkippable.toString(), "http://google.com"));
	eventPixels.add(new EventPixel(EventPixelsEnum.Skip.toString(), "http://yahoo.com"));

	videoCreative.setEventPixels(eventPixels);
  
  VideoCreativeResponse videoCreativeResponse = t1.saveVideoCreatives(videoCreative);

Before second call, get KEY and Uploader Host from GET query, which are needed in second call.

  QueryCriteria query = QueryCriteria.builder().setCollection("creatives").setEntity(Long.parseLong(videoCreativeResponse.getCreativeId())).setCreativeType(CreativeType.video).setChild("upload").build();

  JsonResponse<?> jsonresponse = null;
  try {
  	jsonresponse = t1.get(query);
  } catch (ClientException | ParseException e) {
  	e.printStackTrace();
  }
  VideoCreativeResponse cdr = (VideoCreativeResponse) jsonresponse.getData();

The second call requires the creative id received from the step above. this will return a new VideoCreativeResponse with appropriate status. Use request data from above GET call.

  String filePath = "C:\\dir1\\subdir1\\file1234.flv";
  String fileName = "file1234.flv";
  VideoCreativeUploadResponse uploadResponse = t1.videoCreativeUpload(filePath, fileName, cdr.getKey(), cdr.getUploader().getHost());

you can also check the upload status by calling

  VideoCreativeUploadStatus uploadStatus = t1.getVideoCreativeUploadStatus(videoCreativeResponse.getCreativeId());

which returns a VideoCreativeUplaodStatus obj with appropriate response.

####### Example - Video Creative Update

  //Step 1 : Get Video Creative details
  TerminalOne t1 = new TerminalOne(user, password,production_key);

  QueryCriteria query = QueryCriteria.builder().setCollection("creatives").setEntity(12345).setCreativeType(CreativeType.video).build();

  JsonResponse<?> jsonresponse = null;
  try {
  	jsonresponse = t1.get(query);
  } catch (ClientException | ParseException e) {
  	// TODO Auto-generated catch block
  	e.printStackTrace();
  }
  CreativeDetailsResponse cdr = (CreativeDetailsResponse) jsonresponse.getData();

  //Step 2 : Update Video Creative
  VideoCreative videoCreative = cdr.getDetails();
  videoCreative.setCreativeId(12345);
  videoCreative.setClickthroughUrl("http://www.mysomedomain.com");
  
  VideoCreativeResponse videoCreativeResponse = t1.saveVideoCreatives(videoCreative);

Video Creative Update returns VideoCreativeResponse with CreativeId and Status.

3PAS Creative Upload

the 3PAS creative upload is broken down into two steps as shown below.

  TerminalOne t1 = new TerminalOne(user, password,api_key);
  
  // 3pas first call
  ThreePASCreativeUpload response = t1.save3pasCreativeUpload("C:\\dir1\\subdir1\\file1.txt", "file1" ,"file1");
  
  
  // 3pas second call 
  ThreePASCreativeBatchApprove batchApprove = new ThreePASCreativeBatchApprove();

  batchApprove.setBatchId(response.getBatch().getId());
  batchApprove.setAdvertiserId("123456");
  batchApprove.setBatchIndex("1", null, null);
  batchApprove.setBatchIndex("4", null, null);
  batchApprove.setBatchIndex("3", null, null);
  
  JsonResponse<? extends T1Entity> finalJsonResponse = t1.save3pasCreativeUploadBatch(batchApprove);

the first step is responsible to upload the creative to 3PAS it takes in filePath, fileName, and a Name parameter as its inputs and returns a ThreePASCreativeUpload response.

the second call takes in ThreePASCreativeBatchApprove as its input parameter the setBatchIndex method takes in 3 parametes: batch index, concept id, click url the concept id and click_url are associated to the specific batch index.

batchApprove.setBatchIndex(pBatchIndex, concept, click_url)

the second call returns JsonResponse<? extends T1Entity>.

T1AS Creative Upload

the T1AS Creative upload is done in 2 steps as shown below.

####### Example - Simple File Upload

  TerminalOne t1 = new TerminalOne(user, password,api_key);
  
  TOneASCreativeAssetsUpload response = t1.saveT1ASCreativeAssetsUpload("C:\\dir1\\subdir1\\JPGs.zip", "JPGs.zip", "t1asfileupload");
  
  assertNotNull(response);
  
  TOneASCreativeAssetsApprove creativeAssetsApprove = new TOneASCreativeAssetsApprove(); 
  creativeAssetsApprove.create(false, 
  		"165615", 
  		"http://ad.vendor.com/clicktracker/?id=1234", 
  		"http://theactuallandingpage.com", 
  		"BBVA_CaminoaleÔxito_160x600.swf", 
  		"BBVA_CaminoaleÔxito_160x600.swf", 
  		"665888");
  
  JsonResponse<? extends T1Entity> secondresponse = t1.saveTOneASCreativeAssetsApprove(creativeAssetsApprove);

####### Example - HTML5 Files Upload with Backup File

  TerminalOne t1 = new TerminalOne(user, password,api_key);
  
  //Backup File (Mandatory)
  T1File t1File = new T1File("BBVA_CaminoaleÔxito_160x600.jpg", "BBVA_CaminoaleÔxito_160x600.jpg", "D:\\MediaMath\\html5\\BBVA_CaminoaleÔxito_160x600.jpg");
  //Required Zip File
  T1File t2File = new T1File("BBVA_CaminoaleÔxito_160x600.jpg", "BBVA_CaminoaleÔxito_160x600.zip", "D:\\MediaMath\\html5\\BBVA_CaminoaleÔxito_160x600.zip");

  List<T1File> fileList = new ArrayList<>();
  fileList.add(t1File);
  fileList.add(t2File);
  
  TOneASCreativeAssetsUpload response = t1.saveTOneASCreativeAssetsUpload(fileList);
  
  assertNotNull(response);
  
  TOneASCreativeAssetsApprove creativeAssetsApprove = new TOneASCreativeAssetsApprove(); 
  creativeAssetsApprove.create(false, 
  		"165615", 
  		"http://ad.vendor.com/clicktracker/?id=1234", 
  		"http://theactuallandingpage.com", 
  		"BBVA_CaminoaleÔxito_160x600", 
  		"BBVA_CaminoaleÔxito_160x600.jpg", 
  		"665888");
  
  JsonResponse<? extends T1Entity> secondresponse = t1.saveTOneASCreativeAssetsApprove(creativeAssetsApprove);

the first call to save T1AS Creative Assets uploads the file and returns the TOneASCreativeAssetsApprove obj in response.

the second call to T1AS requires a TOneASCreativeAssetsApprove whose create method requires the following parameters

  TOneASCreativeAssetsApprove.create(boolean is_https, String advertiserid, String landingPage, String click_url, String primary, String backup, String concept)

the second call returns the JsonResponse<? extends T1Entity> object in response which contans the appropriate status.

Reporting

The Reports API on TerminalOne Platform allows advertisers to access, query and aggregate reporting data

There are two types of requests that can be made against Reports API: requests for metadata information, and requests for data retrieval. All data retrieval requests are performed synchronously.

Get the meta data on number of the reports supported by the API
```
  t1 = new TerminalOne(user, password, api_key);
  JsonResponse<? extends T1Entity> jsonresponse = t1.getMeta();
```
the above code snippets fetches all the supported reports information it returns a Meta object containing all the meta data.
Get Individual Report Definition

you can get meta data for each report as shown below.
```
  t1 = new TerminalOne(user, password, api_key);
  MetaData metaResponse = t1.getReportsMeta(Reports.GEO);
```
getReportsMeta takes in Reports enum; select a desired report from the enum

the method returns a MetaData object which contains meta data like dimension and metrics for the specified report.

Get Report Data

retrieve report data as shown below.

t1.getReport(Reports.PERFORMANCE, report);

this method takes in a Reports enum and a ReportCriteria criteria object.

the Report Criteria is used set the filters, dimensions and metrics parameters to query the reporting api, as shown below.

  ReportCriteria report = new ReportCriteria();
  report.setDimension("advertiser_name");
  report.setDimension("campaign_id");
  report.setDimension("campaign_name");
  report.setFilter("organization_id", "=", "100000");
  report.setMetric("impressions");
  report.setMetric("clicks");
  report.setMetric("total_conversions");
  report.setMetric("media_cost");
  report.setMetric("total_spend");
  report.setTime_rollup("by_day");

  SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd");
  String stateDate = df.format(df.parse(dateInString));
  String endDate = df.format(df.parse(endDateInString));
  report.setStart_date(stateDate);
  report.setEnd_date(endDate);

the start date and end date can be specified in the following formats.

month - YYYY-MM
day - YYYY-MM-DD
hour - YYYY-MM-DDThh
minute - YYYY-MM-DDThh:mi
second - YYYY-MM-DDThh:mi:ss

the response is always a file object.

Miscellaneous

Bulk Strategy update using campaign id

Below are the basic steps to follow

1. Get all strategies to update

Example

  FullParamValues fpm = new FullParamValues();
  fpm.setStrValue("strategy");
  Map<String, Long> limitMap = new HashMap<String, Long>();
  limitMap.put("campaign", (long) 12345);
  QueryCriteria query = QueryCriteria.builder().setCollection("strategies").setLimit(limitMap).setFull(fpm).setGetAll(true).build();
  List<Strategy> StrategiesToUpdate = new ArrayList<Strategy>();
  
  JsonResponse<?> jsonresponse = null;
  try {
  	jsonresponse = terminalOne.get(query);
  } catch (ClientException | ParseException e) {
  	e.printStackTrace();
  }
  StrategiesToUpdate = (List<Strategy>) jsonresponse.getData();

2. Create Updater Strategy object

Create new Strategy entity and add parametervalues to it which you want to update in all strategies.

Example

  Strategy updater = new Strategy();
  updater.setBidAggresiveness(100f);
  ...

3. Update Strategies using updater Strategy Update all strategies using method of TerminalOne class as below.

terminalOne.bulkUpdate(StrategiesToUpdate, Updater Strategy)

This method accepts 2 parameters,

1.list of strategies which needs to be updated

2.Updater Strategy object.

Example

  List<Strategy> updatedStrategyList =null;
  updatedStrategyList =	terminalOne.bulkUpdate(StrategiesToUpdate, updater);

Name		Name	Last commit message	Last commit date
Latest commit History 236 Commits
src		src
.gitignore		.gitignore
.project		.project
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml

License

MediaMath/t1-java

Folders and files

Latest commit

History

Repository files navigation

t1-java

Maven Integration

Usage

Authentication - Cookie Auth (default)

OAuth2 (Password - Resource Owner flow):

Fetching Entities and Collections

Searching for entities

How to Post

Example

Video Creatives

3PAS Creative Upload

T1AS Creative Upload

Reporting

Get the meta data on number of the reports supported by the API

Get Individual Report Definition

Get Report Data

Miscellaneous

Bulk Strategy update using campaign id

Example

Example

Example

About

Topics

Resources

License

Stars

Watchers

Forks

Languages