IronSource Promotion API
class PromoteAPI()
IronSource Promote API
def set_credentials(user: str, token: str, secret: str)
sets the API credentials
Arguments:
user
: - user name from the platformtoken
: - token from the platformsecret
: - secret from the platform
def get_skan_reporting(start_date: str,
end_date: str,
metrics: Iterable[Metrics],
breakdowns: Iterable[Breakdowns] = None,
response_format: str = 'json',
count: int = None,
campaign_ids: Iterable[int] = None,
bundle_ids: Iterable[str] = None,
creative_ids: Iterable[int] = None,
country: Iterable[str] = None,
os_sys: Platform = None,
device_type: str = None,
ad_unit: AdUnits = None,
order: Union[Metrics, Breakdowns] = None,
direction: str = 'asc',
as_bytes=False) -> io.BytesIO
SKAN Reporting API
This method returns a BytesIO stream which will contain all responses from the api including pagination The stream will contain new data all the time until there is no more. in case of json, each response will be it's own json array
Arguments:
start_date
: report start date in the following format YYYY-MM-DDend_date
: report end date in the following format YYYY-MM-DDmetrics
: list of report metrics.breakdowns
: list of report breakdowns.response_format
: report format type 'csv' or 'json' only - default 'json'count
: maximum number of records in the reportcampaign_ids
: list of campaign idsbundle_ids
: list of bundle idscreative_ids
: list of creative ids.country
: list of country code in 2 letter country code, as per ISO 3166-1 Alpha-2os_sys
: either 'ios' or 'android'. See Platformdevice_type
: either 'phone' or 'tablet'ad_unit
: Ad Unit. see AdUnitsorder
: a breakdown or metric to order bydirection
: direction of order 'asc' or 'desc' - default 'asc'as_bytes
: in case the return io.BytesIO value should be in bytes
Returns:
io.BytesIO stream that will contain the response example:
bytes_io = iron_src_api.promote_api().get_advertiser_statistics('2020-10-03','2020-10-04',
[Metrics.Impressions,Metrics.Clicks,Metrics.Installs],
[Breakdowns.Application,Breakdowns.Day],response_format='csv')
line = bytes_io_r.readline()
while len(line) > 0:
print(line)
line = bytes_io_r.readline()
bytes_io_r.close()
def get_advertiser_statistics(start_date: str,
end_date: str,
metrics: Iterable[Metrics],
breakdowns: Iterable[Breakdowns] = None,
response_format: str = 'json',
count: int = None,
campaign_ids: Iterable[int] = None,
bundle_ids: Iterable[str] = None,
creative_ids: Iterable[int] = None,
country: Iterable[str] = None,
os_sys: Platform = None,
device_type: str = None,
ad_unit: AdUnits = None,
order: Union[Metrics, Breakdowns] = None,
direction: str = 'asc',
as_bytes=False) -> io.BytesIO
User Acquisition Reporting API
This method returns a BytesIO stream which will contain all responses from the api including pagination The stream will contain new data all the time until there is no more. in case of json, each response will be it's own json array
Arguments:
start_date
: report start date in the following format YYYY-MM-DDend_date
: report end date in the following format YYYY-MM-DDmetrics
: list of report metrics. see Metricsbreakdowns
: list of report breakdowns. see Breakdownsresponse_format
: report format type 'csv' or 'json' only - default 'json'count
: maximum number of records in the reportcampaign_ids
: list of campaign idsbundle_ids
: list of bundle idscreative_ids
: list of creative ids.country
: list of country code in 2 letter country code, as per ISO 3166-1 Alpha-2os_sys
: either 'ios' or 'android' see Platformdevice_type
: either 'phone' or 'tablet'ad_unit
: Ad Unit. see AdUnitsorder
: a breakdown or metric to order bydirection
: direction of order 'asc' or 'desc' - default 'asc'as_bytes
: in case the return io.BytesIO value should be in bytes
Returns:
io.BytesIO stream that will contain the response example:
bytes_io = iron_src_api.promote_api().get_advertiser_statistics('2020-10-03','2020-10-04',
[Metrics.Impressions,Metrics.Clicks,Metrics.Installs],
[Breakdowns.Application,Breakdowns.Day],response_format='csv')
line = bytes_io_r.readline()
while len(line) > 0:
print(line)
line = bytes_io_r.readline()
bytes_io_r.close()
async def get_universal_skan_report(date: str) -> str
returns a copy of the raw winning postbacks data from every network, directly from Apple.
Arguments:
date
: date of the report
Returns:
json with list of urls of the report
def get_bids_for_campaign(campaign_id: int,
max_records: int = 1000,
as_bytes: bool = False) -> io.BytesIO
returns the current bids for a campaign
Arguments:
campaign_id
: the campaign id to fetch bids for.max_records
: maximum number of records per response
Returns:
io.BytesIO stream that will contain the response
async def update_bids(campaign_bids: Iterable[CampaignBidsList])
Update bids for campaigns
Arguments:
campaign_bids
: Array of CampaignBidsList. Each CampaignBidList contain bids for a campaign.
Returns:
array of all update requests and result message from the API. response object example
{'campaignId':1234,'bidsUpdates':999,'msg':'Accepted'}
async def delete_bids(campaign_bids: Iterable[CampaignBidsList])
Delete bids for campaigns
Arguments:
campaign_bids
: Array of CampaignBidsList. Each CampaignBidList contain bids for deletion.
Returns:
array of all delete requests and result message from the API. response object example
{'campaignId':1234,'bidsUpdates':999,'msg':'Accepted'}
async def get_audience_lists()
return all audience lists for the account
Returns:
json array with all audience list For example:
{
"count": 1,
"audiences": [
{
"id": 1,
"type": "targeting",
"name": "batz",
"description": "batz",
"bundleId": "com.adsd.sdf",
"platform": "android",
"lastModified": "2017-01-31T20:00:00.000Z",
"hasActiveCampaigns": true
}
]
}
async def create_audience_list(audience_meta_data: AudienceListMeta)
Creates new Audience List
Arguments:
audience_meta_data
: Meta data of the new audience list. See AudienceListMeta
Returns:
The API response
async def delete_audience_list(audience_list_id: str)
Delete an audience list
Arguments:
audience_list_id
: The audience list to delete in string
Returns:
The API response for deletion
async def update_audience_list(audience_list_data: AudienceListData)
Update Audience lists with device ids
Arguments:
audience_list_data
: Object containing audience lists ids and device ids. See AudienceListData
Returns:
The API response for update of the list
async def get_titles(os_sys: Platform = None,
search_term: str = None,
request_id: str = None,
results_bulk_size: int = None,
page_number: int = None) -> dict
Get list of title
Arguments:
os_sys
(Platform, optional
): Filter titles of a specified os, defaults to None.search_term
(str, optional
): Filter by the name or partial name of the title, defaults to Nonerequest_id
(str, optional
): Used for paginated request, defaults to Noneresults_bulk_size
(int, optional
): Used for paginated request, defaults to Nonepage_number
(int, optional
): Used for paginated request, defaults to None
Raises:
ValueError
: description
Returns:
dict Example ::
{
"titles": [
{
"id": 113366,
"bundleId": "com.yourcompany.MiniGame",
"os": "android",
"name": "Gaming mania"
},
{
"id": 225566,
"bundleId": "com.yourcompany.BestGame",
"os": "ios",
"name": "The Best Game"
},
{
"id": 773366,
"bundleId": "com.yourcompany.MusicGame",
"os": "ios",
"name": "Guitar Music"
}
],
"totalResultsCount": 3,
"requestId": "MzUzMjIuODI5OTk5OS41LjI5"
}``: dictionary with array of the titles
async def get_assets(asset_type: str = None,
title_id: int = None,
ids: Union[int, list] = None,
request_id: str = None,
page_number: int = None,
results_bulk_size: int = None) -> dict
Get List of assets
Arguments:
asset_type
(str, optional
): Filter assets of a specified type. (Options: image, video, html, html_iec), defaults to Nonetitle_id
(int, optional
): Title Id to filter by, defaults to Noneids
(Union[int, list], optional
): Asset id to filter by, defaults to Nonerequest_id
(str, optional
): Used for paginated requests, defaults to Nonepage_number
(int, optional
): Used for paginated requests, defaults to Noneresults_bulk_size
(int, optional
): Used for paginated requests, defaults to None
Raises:
ValueError
:Exception
:
Returns:
dict **Example**: :: { "assets": [ { "id": 200305, "type": "video", "titleId": 501567, "orientation": "all", "source": "none", "duration": 30 }, { "id": 200304, "type": "image", "titleId": 501567, "orientation": "all", "source": "none", "duration": null }, { "id": 200303, "type": "html_iec", "titleId": 501567, "orientation": "all", "source": "playworks", "duration": null } ], "totalResultsCount": 3, "requestId": "MjA1MzUzLjIwMDMwMy40LjM1OTY=" }
: JSON formatted array of the assets
async def create_assets(title_id: int,
asset_type: str,
file_path: str,
file_name: str = None) -> dict
Create Asset to be used with Creative
Arguments:
title_id
(int
): Title id that the asset belongs to.asset_type
(str
): The type of the asset. One of the following: image, video.file_path
(str
): Path to asset file. See details below.file_name
(str, optional
): Name to overwrite file's name, defaults to None
Raises:
ValueError
: descriptionException
: description
Returns:
`dict Files Requirements:
Image File format: png,jpg,jpeg,gif Max file size: 2MB Min dimension: 320px Max dimension: 3,840px Ratio: From 1:2 to 2:1
Video Max file size: 100MB Max duration: 60sec Ratio: From 1:2 to 2:1 Note: Videos longer than 30sec will have limited traffic`: json format with information on the uploaded asset
async def get_creatives(creative_type: CreativeType = None,
title_id: int = None,
request_id: str = None,
page_number: int = None,
results_bulk_size: int = None)
Name - Mandatory - Data type - Description
Arguments:
creative_type
: - No - String - Filter creatives of a specified type. Use CreativeType classtitle_id
: - No - Number - Filter creatives of a specific title.request_id
: - No - String - Used for paginated requests.page_number
: - No - Number - Used for paginated requests.results_bulk_size
: - No - Number - Used for paginated requests.
async def create_creatives(title_id: int,
creatives: Iterable[Creative]) -> dict
Name - Mandatory - Data type - Description
Arguments:
title_id
: - Yes - Int - The title ID.creatives
: - Yes - List - List of creative objects. Use class Creative.
Returns:
dict
: {"success": true,
"ids": [1,2,3]}
Module for Audience List
class AudienceListType(enum.Enum)
Enum for Audience List Types
class AudienceListMeta()
Create AudienceList Object
Arguments:
name
(str
): Audience List name.list_type
(AudienceListType
): Audience List type. see AudienceListType.description
(str
): Audience List description.bundle_id
(str, optional
): Bundle id for the list, defaults to Noneplatform
(Platform, optional
): platform for the audience list. See Platform., defaults to None
class AudienceListData()
Class representing Audience list data
def add_list_for_update(audience_list_id: str)
Add audience list id to the update list
Arguments:
audience_list_id
(str
): audience list id to update in string.
def add_list_for_remove(audience_list_id: str)
Add audience list id to the remove list
Arguments:
audience_list_id
(str
): audience list id to remove in string.
def add_devices(devices: Union[str, list])
Adds devices to the list
Arguments:
devices
(Union[str, list]
): either a device in string or list of devices
Module for Campaign Bids
class CampaignBid()
Class representing a bid Campaign Bid Object that represents a campaign bid
Arguments:
bid
(float
): bid for campaign in floatcountry
(str
): country for bid as per ISO 3166-1 Alpha-2application_id
(int, optional
): application id for bid, defaults to -1
class CampaignBidsList()
Create campaign bid object
Arguments:
campaign_id
(int
): campaign id of the bid
def add_bid(bid: CampaignBid)
Adds a bid to the list
Arguments:
bid
(CampaignBid
): CampgianBid for the campaign bid object
def get_campaign_id()
returns the campaign id
Returns:
campaign id.
Module for Creatives
class Creative()
Class that represents Creative
Arguments:
name
(str
): Name of the creativecreative_type
(CreativeType
): Type of the creative.language
(str
): 2 letter e.g english=”EN”.assets
(Iterable[CreativeAsset], optional
): List of CreativeAsset, defaults to []
def check_asset_compatible(asset: CreativeAsset) -> bool
Checks is CreativeAsset is compatible with the Creative
Arguments:
asset
(CreativeAsset
): Assets to check compatibility
Returns:
bool
: True is compatible else False
def is_validate() -> bool
Check if creative is valid
Returns:
bool
: True if the creative is valid with all it's assets
def add_asset(asset: CreativeAsset)
Adds asset to creative
Arguments:
asset
(CreativeAsset
): CreativeAsset to be added
Raises:
ValueError
: If Asset usage is wrong
class CreativeAsset()
Creative Asset for Creative usage
Arguments:
asset_id
(int
): Asset ID for the creative asset see get_assetsusage_type
(UsageType
): Usage type of the creative
class Metrics(enum.Enum)
Metrics for promote reporting api
class AdUnits(enum.Enum)
Ad Units for promote API
class Breakdowns(enum.Enum)
Breakdowns for promote reporting API
class Platform(enum.Enum)
Platforms for promote API
## UsageType
class UsageType(enum.Enum)
Usage Types for creative API
class CreativeType(enum.Enum)
Creative types for creative API