Marketing API Integration | Xiaomi (2024)

# I. Apply to create an external app

Steps to apply for access to the Marketing API:

1. Contact the corresponding AM and provide the "account ID" and "account name" required to activate the Marketing API

2. The AM makes the application

3. After the application is approved, the AM provides the app details such as appId and appKey

# II. Token acquisition

# 1. Create token

​Interface：https://global.e.mi.com/foreign/token/createToken

Request method： POST

Content-Type：application/json

Request parameters:

Returned values:

{ "code": 0, "message": "Success", "result": { "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6Indtc2oiLCJhcHBLZXkiOiJhYmMxMjMiLCJleHAiOjE2NjU3NDMyODR9.PqIZJbQdrgWe-pseyhJo3sxsGZroIBiasaSmKkh9QCM", "expireDate": "2022-10-14T10:28:04.570Z", "refreshExpireDate": "2022-10-21T09:28:04.570Z", "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJncmFudF90eXBlIjoicmVmcmVzaCIsImFwcElkIjoid21zaiIsImFwcEtleSI6ImFiYzEyMyIsImV4cCI6MTY2NjM0NDQ4NH0.uD3TAbgU6X8ouX-Ra7A4LVKMgb_qi7btNagaG2_2ccY" }}

# 2. Update token

​Interface：https://global.e.mi.com/foreign/token/refreshToken

Request method： POST

Content-Type：application/json

Request parameters:

Returned values:

# III. Setting public parameters

Parameter position:Cookie

# IV. Ad interface

# 1. Campaign

# 1.1 Getting a campaign

Interface：/foreign/marketing/campaign/list

Request method： GET

Content-Type：application/json

Request parameters:

Returned values:

Return example:

{ "code": 0, "message": "Success", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "campaignId": 100205030, "name": "Ad Group 1", "dayBudget": 3000000, "campaignType": 1, }, { "accountId": 1, "campaignId": 100205031, "name": "Ad Group 2", "dayBudget": 3000000, "campaignType": 2, } ] }}

# 1.2 Add a new campaign

Interface：/foreign/marketing/campaign/add

Request method： POST

Content-Type：application/json

Request parameters:

Request example:

[ { "accountId": "1420", "campaignName":"Test Campaign", "campainType": 1, "dayBudget": 3000000, "uniKey": "hNtN5LseHtaAAG0G" }, { "accountId": "1420", "campaignName":"Test Campaign 1", "campainType": 1, "dayBudget": 10000000, "uniKey": "oCtdQktKeC6lsODu" }]

Return example:

{ "code": 0, "message": "Success", "result":[ {"uniKey": "oCtdQktKeC6lsODu", "id":75312748}, {"uniKey": "hNtN5LseHtaAAG0G", "id":93472403} ]}

# 2. Ad group

# 2.1 Getting an ad group

Interface：/foreign/marketing/group/list

Request method： GET

Content-Type：application/json

Request parameters:

Returned values:

Return example:

{ "code": 0, "message": "Success", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "groupId": 100205030, "name": "Ad group 1", "dayBudget": 3000000, "billingType": 11, "productType": 1, "bid": 100000, "region": ["RU","afghanistan_badakhshan_new","616436"], "campaignId": 100205030 }, { "accountId": 1, "groupId": 100205031, "name": "Ad group 2", "dayBudget": 3000000, "billingType": 11, "productType": 1, "bid": 100000, "region": ["RU","afghanistan_badakhshan_new","616436"], "campaignId": 100205030 } ] }}

# 2.2 Add a new ad group

Interface：/foreign/marketing/group/add

Request method： POST

Content-Type：application/json

Request parameters:

Request example:

[ { "accountId": 1420, "campaignId": 75312748, "groupName": "Test Ad Group 1", "packageName": "a.b.c", "productType":1, "settlementType":1, "mediaAndTagIds":{ "all": false, "exclude": [ { "id": 1, "type": "mediaClass", "all": false, "subList": [ { "id": 386, "type": "media", "all": false, "subList": [ { "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] } ] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }, "regions": ["IN","ID"], "billingType": 11, "dayBudget": 3000000, "bid": 10000, "timeZone": "+8", "beginTime": "", "endTime": "", "uniKey": "0ah0Ko2UCl48htsz" }, { "accountId": 1420, "campaignId": 93472403, "groupName": "Test Ad Group 2", "packageName": "a.b.c", "productType":1, "settlementType":1, "mediaAndTagIds":{ "all": false, "exclude": [ { "id": 1, "type": "mediaClass", "all": false, "subList": [ { "id": 386, "type": "media", "all": false, "subList": [ { "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] } ] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }, "regions": ["IN","ID"], "billingType": 11, "dayBudget": 3000000, "bid": 10000, "beginTime": "1711612800000", "endTime": "1711785600000", "uniKey": "yAHqxOaIIw4wnV13" }]

Return example:

{ "code": 0, "message": "Success", "result":[ {"uniKey": "oCtdQktKeC6lsODu", "id":39451985}, {"uniKey": "hNtN5LseHtaAAG0G", "id":98724407} ]}

# 2.3 Modify ad group

Interface：/foreign/marketing/group/update

Request method： POST

Content-Type：application/json

Request parameters:

Request example:

{ "groupIds": [32434,2346], "regions": ["IN","ID"], "dayBudget": 500000, "bid": 100000}

Return example:

{ "code": 0, "message": "Success"}

# 2.4 Retrieve country list

Interface：/foreign/marketing/region/countryList

Request method： GET

Content-Type：application/json

Return example:

{ "code": 0, "message": "Success", "result": [ { "geoType": "COUNTRY", "id": "AF", "name": "Afghanistan" }, { "geoType": "COUNTRY", "id": "AX", "name": "Aland islands" } ]}

# 2.5 Retrieve the regions in a country

Interface：/foreign/marketing/region/getByCountry

Request method： GET

Content-Type：application/json

Request parameters:

Return example:

{ "code": 0, "message": "Success", "result": [ { "geoType": "PROVINCE", "id": "afghanistan_badakhshan_new", "name": "badakhshan", "subGeo":[ { "geoType": "CITY", "id": "616418", "name": "ab barek" }, { "geoType": "CITY", "id": "616436", "name": "ab chanar" } ] }, { "geoType": "PROVINCE", "id": "afghanistan_badghis_new", "name": "badghis" } ]}

# 2.6 Retrieve media based on ad group ID (for modifications)

Interface：/foreign/marketing/group/getMediaList

Request method： GET

Content-Type：application/json

Request parameters:

Return example:

Preferred placement:

[ { "groupId":123456, "desc": "Preferred placement", "description": "", "id": 1, "name": "Preferred placement", "subSelectOption": [ { "desc": "Internal media", "description": "", "id": 1, "name": "Internal media", "subSelectOption": [ { "desc": "Global App vault (widget)", "description": "", "id": 386, "name": "Global App vault (widget)", "subSelectOption": [ { "desc": "1.386.1.1", "description": "", "id": "1.386.1.1", "name": "1.386.1.1", "isSelected": true } ] } ] }, { "desc": "Affiliate media", "description": "", "id": 4, "name": "Affiliate media", "subSelectOption": [ { "desc": "Test App Android", "description": "", "id": 512, "name": "Test App Android", "subSelectOption": [ { "desc": "1.512.29.1", "description": "", "id": "1.512.29.1", "name": "1.512.29.1", "isSelected": false } ] } ] } ] } ]

or self-selected placement:

[ { "groupId":123456, "desc": "Self-selected Placement", "description": "", "id": 2, "name": "Self-selected Placement", "subSelectOption": [ { "desc": "Banner", "description": "", "id": 6, "name": "Banner", "subSelectOption": [ { "desc": "Internal media", "description": "", "id": 1, "name": "Internal media", "subSelectOption": [ { "desc": "MSASDK_DEMO", "description": "", "id": 300, "name": "MSASDK_DEMO", "subSelectOption": [ { "desc": "1.300.2.5", "description": "", "id": "1.300.2.5", "name": "1.300.2.5", "isSelected": false } ] } ] }, { "desc": "Affiliate media", "description": "", "id": 4, "name": "Affiliate media", "subSelectOption": [ { "desc": "Word Search Block Puzzle Game", "description": "", "id": 511, "name": "Word Search Block Puzzle Game", "subSelectOption": [ { "desc": "1.511.2.1", "description": "", "id": "1.511.2.1", "name": "1.511.2.1", "isSelected": true } ] } ] } ] } ] }]

# 2.7 Retrieve media based on campaign ID (for new entries)

Interface：/foreign/marketing/group/getMediaListByCampaign

Request method： GET

Content-Type：application/json

Request parameters:

Return example:

Preferred placement:

[ { "desc": "Preferred placement", "description": "", "id": 1, "name": "Preferred placement", "campaignId": 13682, "subSelectOption": [ { "desc": "Internal media", "description": "", "id": 1, "name": "Internal media", "subSelectOption": [ { "desc": "Global App vault (widget)", "description": "", "id": 386, "name": "Global App vault (widget)", "subSelectOption": [ { "desc": "1.386.1.1", "description": "", "id": "1.386.1.1", "name": "1.386.1.1", "isSelected": true } ] } ] }, { "desc": "Affiliate media", "description": "", "id": 4, "name": "Affiliate media", "subSelectOption": [ { "desc": "Test App Android", "description": "", "id": 512, "name": "Test App Android", "subSelectOption": [ { "desc": "1.512.29.1", "description": "", "id": "1.512.29.1", "name": "1.512.29.1", "isSelected": false } ] } ] } ] } ]

# 2.8 Modify media

Interface：/foreign/marketing/group/media/update

Request method： POST

Content-Type：application/json

Request parameters:

Request example:

{ "groupIds": [12174], "mediaAndTagIds": { "all": false, "exclude": [{ "id": 1, "type": "mediaClass", "all": false, "subList": [{ "id": 386, "type": "media", "all": false, "subList": [{ "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] }, { "id": "1.386.1.4", "type": "tagId", "all": true, "subList": [] }, { "id": "1.386.4.1", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.1.3", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.1.22", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.4.10001", "type": "tagId", "all": false, "subList": [] } ] }, { "id": 665, "type": "media", "all": false, "subList": [] }, { "id": 666, "type": "media", "all": false, "subList": [] }, { "id": 668, "type": "media", "all": false, "subList": [] }, { "id": 670, "type": "media", "all": false, "subList": [] }, { "id": 673, "type": "media", "all": false, "subList": [] }, { "id": 674, "type": "media", "all": false, "subList": [] }, { "id": 676, "type": "media", "all": false, "subList": [] }, { "id": 678, "type": "media", "all": false, "subList": [] }, { "id": 301, "type": "media", "all": false, "subList": [] }, { "id": 302, "type": "media", "all": false, "subList": [] }, { "id": 303, "type": "media", "all": false, "subList": [] }, { "id": 304, "type": "media", "all": false, "subList": [] }, { "id": 305, "type": "media", "all": false, "subList": [] }, { "id": 433, "type": "media", "all": false, "subList": [] }, { "id": 306, "type": "media", "all": false, "subList": [] }, { "id": 307, "type": "media", "all": false, "subList": [] }, { "id": 308, "type": "media", "all": false, "subList": [] }, { "id": 309, "type": "media", "all": false, "subList": [] }, { "id": 310, "type": "media", "all": false, "subList": [] }, { "id": 311, "type": "media", "all": false, "subList": [] }, { "id": 312, "type": "media", "all": false, "subList": [] }, { "id": 313, "type": "media", "all": false, "subList": [] }, { "id": 314, "type": "media", "all": false, "subList": [] }, { "id": 315, "type": "media", "all": false, "subList": [] }, { "id": 317, "type": "media", "all": false, "subList": [] }, { "id": 319, "type": "media", "all": false, "subList": [] }, { "id": 323, "type": "media", "all": false, "subList": [] }, { "id": 324, "type": "media", "all": false, "subList": [] }, { "id": 325, "type": "media", "all": false, "subList": [] }, { "id": 328, "type": "media", "all": false, "subList": [] }, { "id": 329, "type": "media", "all": false, "subList": [] }, { "id": 330, "type": "media", "all": false, "subList": [] }, { "id": 460, "type": "media", "all": false, "subList": [] }, { "id": 332, "type": "media", "all": false, "subList": [] }, { "id": 333, "type": "media", "all": false, "subList": [] }, { "id": 334, "type": "media", "all": false, "subList": [] }, { "id": 335, "type": "media", "all": false, "subList": [] }, { "id": 336, "type": "media", "all": false, "subList": [] }, { "id": 337, "type": "media", "all": false, "subList": [] }, { "id": 338, "type": "media", "all": false, "subList": [] }, { "id": 339, "type": "media", "all": false, "subList": [] }, { "id": 340, "type": "media", "all": false, "subList": [] }, { "id": 343, "type": "media", "all": false, "subList": [] }, { "id": 344, "type": "media", "all": false, "subList": [] }, { "id": 347, "type": "media", "all": false, "subList": [] }, { "id": 349, "type": "media", "all": false, "subList": [] }, { "id": 350, "type": "media", "all": false, "subList": [] }, { "id": 351, "type": "media", "all": false, "subList": [] }, { "id": 352, "type": "media", "all": false, "subList": [] }, { "id": 353, "type": "media", "all": false, "subList": [] }, { "id": 354, "type": "media", "all": false, "subList": [] }, { "id": 355, "type": "media", "all": false, "subList": [] }, { "id": 356, "type": "media", "all": false, "subList": [] }, { "id": 357, "type": "media", "all": false, "subList": [] }, { "id": 358, "type": "media", "all": false, "subList": [] }, { "id": 359, "type": "media", "all": false, "subList": [] }, { "id": 360, "type": "media", "all": false, "subList": [] }, { "id": 361, "type": "media", "all": false, "subList": [] }, { "id": 362, "type": "media", "all": false, "subList": [] }, { "id": 363, "type": "media", "all": false, "subList": [] }, { "id": 364, "type": "media", "all": false, "subList": [] }, { "id": 365, "type": "media", "all": true, "subList": [] }, { "id": 366, "type": "media", "all": false, "subList": [] }, { "id": 367, "type": "media", "all": false, "subList": [] }, { "id": 368, "type": "media", "all": false, "subList": [] }, { "id": 369, "type": "media", "all": false, "subList": [] }, { "id": 370, "type": "media", "all": false, "subList": [] }, { "id": 371, "type": "media", "all": false, "subList": [] }, { "id": 628, "type": "media", "all": false, "subList": [] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }}

Return example:

{ "code": 0, "message": "Success"}

Attribute meaning:

include： Used for custom placementexclude：Used for preferred placementall：Select allsubList：Required when isAll is false; empty when isAll is true

# 3. Ad creative

# 3.1 Retrieve ad creative

Interface：/foreign/marketing/creative/list

Request method： GET

Content-Type：application/json

Request parameters:

Returned values:

Return example:

{ "code": 0, "message": "Success", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "groupId": 1234, "creativeId": 100205030, "name": "Ad Creative Name 1", "landingUrl": "https://s.click.aliexpress.com/e/_DC4tkHX", "exposeMonitorUrl": "https://s.click.aliexpress.com/e/_DC4tkHX34" }, { "accountId": 1, "groupId": 1234, "creativeId": 100205031, "name": "Ad Creative Name 2", "landingUrl": "https://s.click.aliexpress.com/e/_DC4tkHX", "exposeMonitorUrl": "https://s.click.aliexpress.com/e/_DC4tkHX34" } ] }}

# 33.2 Add a new ad creative

Interface：/foreign/marketing/creative/add

Request method： POST

Content-Type：application/json

Request parameters:

Request example:

[ { "accountId": 307, "groupId": 103038, "creativeName": "Test Ad Creative 1", "imgUrls": [{"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/041d8edcec8cf4635bc3e805fa21a28d8c31844de/041d8edcec8cf4635bc3e805fa21a28d8c31844de.png","materialId":153188815,"width":600,"height":500},{"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/08e6d9c772e28432990b3e71a53d0a6367327cc7f/08e6d9c772e28432990b3e71a53d0a6367327cc7f.png","materialId":153188881,"width":600,"height":500}], "iconUrl": {"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/jpeg/w1000/AdCenter/00f663f09d257480f9cbc309f8d0742f4cce661f1/00f663f09d257480f9cbc309f8d0742f4cce661f1.jpeg","materialId":168227440,"width":84,"height":84}, "title": "Title", "description": "Description", "button": "Install", "landingUrl": "https://magnifier.sng.link/B0dnr/pj8j?_dl=com.mobileguru.fruitgardenblast.free%3A%2F%2F&aifa={gaid}&pcid={groupId}&cl={ext}&pcn={campaignId}&pshid={tagId}", "deeplinkUrl": "lazada://sg/web/www/marketing/gateway/index.html?null&dsource=sml&exlaz=e_DoiSug0NEP7Gip8qo24MCfU%252BqLKrZhcY%252BYT1MfH074zCXvTKdNAtBekmwronlsSBS2AvU1L%252BAVXJaw5ibSqRgt7gRm2qOE7bD3WnASIas1Y%253D&os=Android&gps_adid={gaid}&device_make=xiaomi&adtype=Push&sub_id1={ext}&rta_event_id={triggerId}", "uniKey": "QFHJU2Xpa00nC4Tr" }]

Return example:

{ "code": 0, "message": "Success", "result":[ {"uniKey": "QFHJU2Xpa00nC4Tr", "id":33858248} ]}

# 3.3 Modify ad creative

Interface：/foreign/marketing/creative/update

Request method： POST

Content-Type：application/json

Request parameters:

Request example:

{ "creativeIds": [32434,2346], "landingUrl": "https://xxxx", "exposeMonitorUrl": "https://xxxx"}

Return example:

{ "code": 0, "message": "Success"}

# 3.4 Upload files

Interface：/foreign/marketing/upload

Request method： POST

Content-Type：application/json

Return example:

{ "code": 0, "message": "", "result": { "height": 261, "id": 41491554, "url": "https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/076eeb887cf3c41aa9e9f1d87d96ab372c716ecd3/076eeb887cf3c41aa9e9f1d87d96ab372c716ecd3.png", "width": 1080 }}

# Code reference table