tune_reporting 2.5.0

TUNE Reporting API client library.

.. -*- mode: rst -*-

tune-reporting-python
---------------------

TUNE Reporting API client library.


Badges
------

.. start-badges

.. list-table::
:stub-columns: 1

* - docs
- |docs| |license|
* - info
- |hits| |contributors|
* - tests
- |travis| |coveralls|
* - package
- |version| |supported-versions|
* - other
- |requires|

.. |docs| image:: https://readthedocs.org/projects/tune-reporting-python/badge/?style=flat
:alt: Documentation Status
:target: http://tune-reporting-python.readthedocs.io

.. |hits| image:: http://hits.dwyl.io/TuneLab/tune-reporting-python.svg
:alt: Hit Count
:target: http://hits.dwyl.io/TuneLab/tune-reporting-python

.. |license| image:: https://img.shields.io/badge/License-MIT-yellow.svg
:alt: License Status
:target: https://opensource.org/licenses/MIT

.. |travis| image:: https://travis-ci.org/TuneLab/tune-reporting-python.svg?branch=master
:alt: Travis-CI Build Status
:target: https://travis-ci.org/TuneLab/tune-reporting-python

.. |coveralls| image:: https://coveralls.io/repos/TuneLab/tune-reporting-python/badge.svg?branch=master&service=github
:alt: Code Coverage Status
:target: https://coveralls.io/r/TuneLab/tune-reporting-python

.. |requires| image:: https://requires.io/github/TuneLab/tune-reporting-python/requirements.svg?branch=master
:alt: Requirements Status
:target: https://requires.io/github/TuneLab/tune-reporting-python/requirements/?branch=master

.. |version| image:: https://img.shields.io/pypi/v/tune_reporting.svg?style=flat
:alt: PyPI Package latest release
:target: https://pypi.python.org/pypi/tune_reporting

.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/tune_reporting.svg?style=flat
:alt: Supported versions
:target: https://pypi.python.org/pypi/tune_reporting


.. end-badges


Install
-------

.. code-block:: bash

pip install tune_reporting


Requirements
------------

:Prerequisites: Python 3.0
:API Key: To use SDK, it requires you to `Generate API Key <https://developers.tune.com/management-docs/resource-authentication-user-permissions//>`_


Run Examples
------------

.. code-block:: bash

make run-examples tmc_api_key=[TMC API KEY]


Run Tests
---------

.. code-block:: bash

make test tmc_api_key=[TMC API KEY]


Classes
-------

There are multiple TUNE API Classes available:

- ``TuneV2Advertisers``
- ``TuneV2AdvertiserSites``
- ``TuneV2AdvertiserStatsActuals``
- ``TuneV2SessionAuthenticate``
- ``TuneV3LogsAdvertisersClicks``
- ``TuneV3LogsAdvertisersImpressions``


-------------------------


``class TuneV2Advertisers``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Get **``ADVERTISER ID``** for this account based upon provided **``TMC_API_KEY``**.

**Code**

.. code-block:: python

tune_v2_advertisers = TuneV2Advertisers(
logger_level=logging.INFO,
logger_format=LoggingFormat.JSON,
logger_output=LoggingOutput.STDOUT_COLOR
)

try:
tune_v2_advertisers.tmc_auth(tmc_api_key=tmc_api_key)

if tune_v2_advertisers.get_advertiser_id(
auth_value=tmc_api_key,
auth_type=TuneV2AuthenticationTypes.API_KEY,
request_retry=None
):
advertiser_id = tune_v2_advertisers.advertiser_id
pprint(advertiser_id)

except TuneRequestBaseError as tmc_req_ex:
print_traceback(tmc_req_ex)
pprint(tmc_req_ex.to_dict())
print(str(tmc_req_ex))

except TuneReportingError as tmc_rep_ex:
pprint(tmc_rep_ex.to_dict())
print(str(tmc_rep_ex))

except Exception as ex:
print_traceback(ex)
print(get_exception_message(ex))


**Example**

.. code-block:: bash

$ cd examples
$ make example_tune_v2_advertisers tmc_api_key=[ ... TMC API-Key ...]

{"asctime": "2017-11-29 08:58:30 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC Authentication: Start"}
{"asctime": "2017-11-29 08:58:31 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TMC Authentication: Finished", "request_time_msecs": 635}
{"asctime": "2017-11-29 08:58:31 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC v2 Advertisers: Advertiser ID"}
{"asctime": "2017-11-29 08:58:31 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TMC v2 Advertisers: Finished", "request_time_msecs": 260}
{"asctime": "2017-11-29 08:58:31 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC v2 Advertisers: Advertiser ID: [ADVERTISER ID]"}

[ADVERTISER ID]


-------------------------


``class TuneV2SessionAuthenticate``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Get time-limited **``SESSION TOKEN``** after authenticating provided **``TMC_API_KEY``**.

**Code**

.. code-block:: python

tune_v2_session_authenticate = \
TuneV2SessionAuthenticate(
logger_level=logging.INFO
)

try:
if tune_v2_session_authenticate.get_session_token(
tmc_api_key=tmc_api_key,
request_retry=None
):
session_token = tune_v2_session_authenticate.session_token
print(session_token)

except TuneRequestBaseError as tmc_req_ex:
print_traceback(tmc_req_ex)
pprint(tmc_req_ex.to_dict())
print(str(tmc_req_ex))

except TuneReportingError as tmc_rep_ex:
pprint(tmc_rep_ex.to_dict())
print(str(tmc_rep_ex))

except Exception as ex:
print_traceback(ex)
print(get_exception_message(ex))


**Example**

.. code-block:: bash

$ cd examples
$ make example_tune_v2_session_authenticate tmc_api_key=[ ... TMC API-Key ...]

{"asctime": "2017-11-29 09:11:09 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC v2 Session Authenticate: Get Token"}
{"asctime": "2017-11-29 09:11:11 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TMC v2 Session Authenticate: Finished", "request_time_msecs": 1550}
{"asctime": "2017-11-29 09:11:11 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC v2 Session Authenticate", "session_token": "[SESSION TOKEN]"}
{"asctime": "2017-11-29 09:11:11 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC v2 Session Authenticate: Finished"}

[SESSION TOKEN]


-------------------------


``class TuneV2AdvertiserSites``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Get listing of Advertiser's Mobile Apps (aka Sites) for this account based upon provided **``TMC_API_KEY``**.

**Code**

.. code-block:: python

tune_advertiser_sites = TuneV2AdvertiserSites(
logger_level=logging.INFO
)

try:
tune_advertiser_sites.tmc_auth(tmc_api_key=tmc_api_key)

for collect_data_item, collect_error in tune_advertiser_sites.collect(
auth_value=tmc_api_key,
auth_type=TuneV2AuthenticationTypes.API_KEY,
auth_type_use=TuneV2AuthenticationTypes.API_KEY,
request_params={'limit': 5}
):
pprint(collect_data_item)

except TuneRequestBaseError as tmc_req_ex:
print_traceback(tmc_req_ex)
pprint(tmc_req_ex.to_dict())
print(str(tmc_req_ex))

except TuneReportingError as tmc_rep_ex:
print_traceback(tmc_rep_ex)
pprint(tmc_rep_ex.to_dict())
print(str(tmc_rep_ex))

except Exception as ex:
print_traceback(ex)
print(get_exception_message(ex))


**Example**

.. code-block:: bash

$ cd examples
$ make example_tune_v2_advertiser_sites tmc_api_key=[ ... TMC API-Key ...]

{"asctime": "2017-11-29 09:04:25 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC Authentication: Start"}
{"asctime": "2017-11-29 09:04:25 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TMC Authentication: Finished", "request_time_msecs": 593}
{"asctime": "2017-11-29 09:04:25 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "Start Advertiser Sites find"}
{"asctime": "2017-11-29 09:04:26 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TuneV2AdvertiserSites.collect: Finished", "request_time_msecs": 263}

[JSON RESPONSE]
{
'id': 533,
'name': 'TEST UP TIME - DONT DELETE',
'package_name': 'unknown',
'status': 'active',
'url': 'http://website.com',
}
...


-------------------------


``class TuneV2AdvertiserStatsActuals``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Logs of Advertiser's Actuals Stats for this account based upon provided **``TMC_API_KEY``**.

**Code**

.. code-block:: python

tune_v2_advertiser_stats_actuals = \
TuneV2AdvertiserStatsActuals(
logger_level=logging.INFO,
logger_format=LoggingFormat.JSON,
logger_output=LoggingOutput.STDOUT_COLOR
)

tz = pytz.timezone("America/New_York")
yesterday = datetime.now(tz).date() - timedelta(days=1)
str_yesterday = str(yesterday)

try:
auth_response = tune_v2_advertiser_stats_actuals.tmc_auth(tmc_api_key=tmc_api_key)
assert auth_response

tune_v2_advertiser_stats_actuals.collect(
auth_value=tmc_api_key,
auth_type=TuneV2AuthenticationTypes.API_KEY,
auth_type_use=TuneV2AuthenticationTypes.API_KEY,
start_date=str_yesterday,
end_date=str_yesterday,
request_params={
'timezone': 'America/Los_Angeles',
'format': TuneV2AdvertiserStatsFormats.CSV,
'fields': (
"ad_clicks,"
"ad_clicks_unique,"
"ad_impressions,"
"ad_impressions_unique,"
"ad_network_id,"
"advertiser_id,"
"country.code,"
"date_hour,"
"events,"
"installs,"
"is_reengagement,"
"payouts,"
"publisher_id,"
"publisher_sub_ad.ref,"
"publisher_sub_adgroup.ref,"
"publisher_sub_campaign.ref,"
"publisher_sub_publisher.ref,"
"publisher_sub_site.ref,"
"site_id"
),
'group': (
"country_id,"
"is_reengagement,"
"publisher_id,"
"publisher_sub_ad_id,"
"publisher_sub_adgroup_id,"
"publisher_sub_campaign_id,"
"publisher_sub_publisher_id,"
"publisher_sub_site_id,"
"site_id"
),
'timezone': "America/Los_Angeles",
'limit': 5
},
request_action=TuneV2AdvertiserStatsActions.EXPORT,
request_retry={'delay': 15,
'timeout': 30,
'tries': 10}
)

except TuneRequestBaseError as tmc_req_ex:
print_traceback(tmc_req_ex)
pprint(tmc_req_ex.to_dict())
print(str(tmc_req_ex))

except TuneReportingError as tmc_rep_ex:
pprint(tmc_rep_ex.to_dict())
print(str(tmc_rep_ex))

except Exception as ex:
print_traceback(ex)
print(get_exception_message(ex))

for row in list(tune_v2_advertiser_stats_actuals.generator):
pprint(row)


**Example**

.. code-block:: bash

$ cd examples
$ make example_tune_v2_advertiser_stats_actuals_export_download tmc_api_key=[ ... TMC API-Key ...]

{"asctime": "2017-11-29 09:17:21 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC Authentication: Start"}
{"asctime": "2017-11-29 09:17:22 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TMC Authentication: Finished", "request_time_msecs": 516}
{"asctime": "2017-11-29 09:17:22 -0800", "levelname": "INFO", "name": "tune_reporting", "version": "2.3.1",
"message": "TMC v2 Advertiser Stats: Collect: export"}
{"asctime": "2017-11-29 09:17:23 -0800", "levelname": "INFO", "name": "requests_mv_integrations", "version": "00.06.01",
"message": "TMC v2 Advertiser Stats Find: Finished", "request_time_msecs": 1490}

[ADVERTISER ACTUALS STATS]
{
'ad_clicks': '48',
'ad_clicks_unique': '0',
'ad_impressions': '0',
'ad_impressions_unique': '0',
'ad_network_id': 0,
'advertiser_id': 877,
'conversions': '0',
'country': {'code': 'NL', 'name': 'Netherlands'},
'country_id': 528,
'currency_code': 'USD',
'date_hour': '2017-11-28 19:00:00',
'events': '0',
'installs': '0',
'is_reengagement': '0',
'payouts': '0.00000',
'publisher': {'name': 'PINGDOM DO_NOT_DELETE'},
'publisher_id': 142476,
'publisher_sub_ad': {'ref': ''},
'publisher_sub_ad_id': '0',
'publisher_sub_adgroup': {'ref': ''},
'publisher_sub_adgroup_id': '0',
'publisher_sub_campaign': {'ref': ''},
'publisher_sub_campaign_id': '0',
'publisher_sub_publisher': {'ref': ''},
'publisher_sub_publisher_id': '0',
'publisher_sub_site': {'ref': ''},
'publisher_sub_site_id': '0',
'purchase_validation_status': '0',
'site': {
'mobile_app_type': 'iOS',
'package_name': 'unknown',
'store_app_id': None,
},
'site_id': 533,
}
...


License
-------

`MIT License <http://opensource.org/licenses/MIT>`_.


.. :changelog:

Release History
===============

2.4.2 (2017-12-10)
------------------
- readthedocs.org

2.4.0 (2017-11-29)
------------------
- README
- Travis CI
- Tests
- Examples

2.2.3 (2017-11-19)
------------------
- Tests

2.2.1 (2017-10-27)
------------------
- Support logging-mv-integrations refactor

2.2.0 (2017-03-26)
------------------
- Replace 'json' with 'ujson'

2.1.8 (2017-03-12)
------------------
- Switch to using safe-cast package

2.1.7 (2017-02-27)
------------------
- Requirements

2.1.6 (2017-02-07)
------------------
- Requirements

2.1.5 (2017-02-03)
------------------
- Python 3.6 Upgrade

2.1.2 (2017-01-27)
------------------
- Cleanup
- Requirements

2.1.0 (2017-01-14)
------------------
- README.rst
- HISTORY.rst
- setup.py

2.0.0 (2016-11-20)
------------------
- TUNE Reporting API v3

1.1.1 (2016-01-25)
------------------
- TUNE Reporting API v2
- Changes in Handling Exports and Logs

1.0.0 (2015-04-01)
------------------
- TUNE Reporting API v2
- Initial PyPi release

0.0.1 (2014-10-15)
------------------
- First Commit