Mobile API v5

Caution

API v1-v4 are deprecated and new mobile apps should not use them.

Endpoints

Pre-production:

https://pushcamp-windtre-preprod.monksoftware.it/api/v5/mobile/

Production:

https://pushcamp-windtre.monksoftware.it/api/v5/mobile/

Common parameters

Every API call made from clients to the Pushcamp API must provide these parameters:

  • nid: a unique device identifier

  • bundle: e.g. “it.wind.myWind”, needed for multi-bundle environments like Pre-prod where the same NID can be registered many times with different bundles and have different set of news, offers, filters.

Common Responses and Error handling

{"error": true, "status": 400, "code": "BAD_DATA"}

App sent wrong data or some required parameters are missing. In this case app should not retry with exact same request.

{"error": true, "status": 400, "code": "INTERNAL_SERVER_ERROR"}

Temporary error on backend, ie: database is not reachable. Application should retry the same request after some delay.

{"error": true, "status": 400, "code": "NID_NOT_FOUND"}

For some reason device was not found in DB. Application MUST send new /initialize request.

{"success": true, "status": 200}

Successful request.

POST /initialize

Initialize a device, registering it in the Pushcamp system. Clients send a unique device identifier (NID), bundle, and a firebase token that Pushcamp can use to send notifications to the device.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

token

N

Firebase token

delivery_method

N

“google” or “huawei” (defaults to “google”)

Try with curl in Pre-production:

curl --data 'nid=fake-nid&bundle=it.wind.test.app&token=fake-fcm-token' https://pushcamp-windtre-preprod.monksoftware.it/api/v4/mobile/initialize

POST /info

Send device, os, and app information like model, app and sdk versions, notifications status etc.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

data

Y

stringified JSON

Sample of data JSON. Currently backend reads only: appVersion, sdkVersion, brand, device, os, model, language, networkOperator, notificationsBlocked

{
    "appVersion":"1.0.0.24",
    "board":"sdm845",
    "bootloader":"unknown",
    "brand":"OnePlus",
    "codename":"REL",
    "device":"OnePlus6T",
    "display":"ONEPLUS A6013_41_191214",
    "fingerprint":"OnePlus/OnePlus6T/OnePlus6T:10/QKQ1.190716.003/1912142009:user/release-keys",
    "hardware":"qcom",
    "host":"rd-build-74",
    "id":"QKQ1.190716.003",
    "incremental":"1912142009",
    "language":"it",
    "manufacturer":"OnePlus",
    "model":"ONEPLUS A6013",
    "networkCellId":"",
    "networkCellLocation":"",
    "networkLevelSignal":"100",
    "networkOperator":"I WIND",
    "networkType":"WIFI",
    "notificationsBlocked":false,
    "os":"android",
    "osVersion":"4.9.179-perf+",
    "product":"OnePlus6T",
    "release":"10",
    "sdkVersion":"1.3.2",
    "serial":"unknown",
    "tags":"release-keys",
    "time":"1576325845000",
    "type":"user",
    "user":"jenkins"
}

POST /set_user_ids

Send the phone numbers (msisdn) associated with this device. A single device can manage more than one number.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

userIds

Y

array of msisdn, e.g. [“3282737060”,”3294538634”]

Try with curl in Pre-production:

curl --data 'nid=fake-nid&bundle=it.wind.test.app&userIds=["3282737060","3294538634"]' https://pushcamp-windtre-preprod.monksoftware.it/api/v4/mobile/set_user_ids

POST /set_filters

For each msisdn managed by the device send the values of the filters defined in Pushcamp.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

data

Y

stringified JSON [“key”:””, “value”:””, “msisdn”: “”]

Available filters:

Key

Type

Values

os

STRING

“android” or “iOS”

isPrepaid

BOOLEAN

“true”

isPostpaid

BOOLEAN

“true”

isWind

BOOLEAN

“true” or “false” (Wind or H3G will be assigned)

Sample of data:

[
    {
        "key":"isPrepaid",
        "msisdn":"3383035993",
        "type":"BOOLEAN",
        "value":"true"
    },
    {
        "key":"isPostpaid",
        "msisdn":"3920705103",
        "type":"BOOLEAN",
        "value":"true"
    },
    {
        "key":"isWind",
        "msisdn":"3318050284",
        "type":"BOOLEAN",
        "value":"true"
    },
    {
        "key":"os",
        "msisdn":"3920705103",
        "type":"STRING",
        "value":"android"
    }
]

POST /config

This endpoint has few purposes:

  • update last activity and firebase token in Pushcamp DB

  • return bool flags for news and offers letting know the device if there is something new to fetch from the server

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

token

Y

Firebase token

timestampNews

Y

BIGINT timestamp when the app updated list of news

timestampNewsTRM

Y

BIGINT timestamp when the app updated list of TRM news

timestampNewsOffers

Y

BIGINT timestamp when the app updated list of offers

Expected response: {"success":true,"status":200,"updateNews":true,"updateNewsTRM":true,"updateNewsOffers":true}

POST /offer_activated

Remove offer from the news/offers list. This is not the same as offer_required receipt. App should call this endpoint if TRM returns some kind of error that offer is already activated or is incompatible with a selected msisdn.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

newsId

Y

INTEGER id of news/offer

msisdn

Y

active msisdn which tried to activated offer

campaignCode

Y

campaignCode associated with the news/offer

POST /receipt

Send Push or News receipt. See “Receipt Types” page for more details.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

msisdn

Y

msisdn from the offer

receiptType

Y

See “Receipt Types” page

datetime

Y

INT timestamp of event

receiptData

Y

AS IS from news details

POST /logout

Delete all msisdn and filters associated with the device. This does not delete NID or Firebase token from DB.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

Try with curl in Pre-production:

curl --data 'nid=fake-nid&bundle=it.wind.test.app' https://pushcamp-windtre-preprod.monksoftware.it/api/v4/mobile/logout

GET /get_all_news

Returns the list of news per msisdn.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

msisdn

Y

active msisdn

See sample response below. Note that receiptData is a stringified JSON. Application should not use any data from receiptData, but pass it AS IS to backend in all further /receipt requests

{
    "success": true,
    "status":200,
    "news":[

    ],
    "newsTRM":[
        {
            "id":201,
            "campaignCode":"1000mfjhlxn9",
            "category":null,
            "created_at":1580461802000,
            "updated_at":1580745833000,
            "title":"Week-end a Villa Crespi con cena stellata!",
            "short_description":"Una dimora di lusso sul Lago D’Orta",
            "long_description":"html text here",
            "id_manuale":null,
            "cta_visibility":"1",
            "cta_manual_label":"SCOPRI",
            "cta_action":"LINK",
            "cta_manual_param":"https://www.wind.it/winday-partecipa",
            "section":"jakala",
            "image_url":"http://d1594bg0curop3.cloudfront.net/20200130_CONCORSO_banner_winday-villa-crespi.gif",
            "image_desc":"",
            "topNews":false,
            "icon":"http://d1594bg0curop3.cloudfront.net/img_mywind_news_white.png",
            "inbound":false,
            "receiptData":{
                "campaignId":1211,
                "campaignCode":"1000mfjhlxn9",
                "collateralCode":"1000mfjhlzlq",
                "msisdn":"00393200106398",
                "newsId":201,
                "channel":"trm_news"
            }
        }
    ]
}

GET /get_commercial_and_inbound_news

Returns the list of both Inbound and Outbound offers per msisdn.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

msisdn

Y

active msisdn

channel

Y

“APPW3_INB” if msisdn is Wind, “APPW3_INB_3” if Tre

See sample response below. Note that receiptData is a stringified JSON. Application should not use any data from receiptData, but pass it AS IS to backend in all further /receipt requests

{
    "success": true,
    "status":200,
    "news":[

    ],
    "newsTRM":[
         {
            "id":84,
            "campaignCode":null,
            "category":"21464",
            "created_at":1576063721000,
            "updated_at":1579777634000,
            "title":"3 GIGA x TE",
            "short_description":"3 GIGA x TE",
            "long_description":"3 GIGA x TE description",
            "id_manuale":null,
            "cta_visibility":"1",
            "cta_manual_label":"SCOPRI",
            "cta_action":"OFFERTA",
            "cta_manual_param":"ROPZ4545_POPZ000516",
            "section":"",
            "image_url":"http://d1594bg0curop3.cloudfront.net/3_giga_x_te.jpg",
            "image_desc":"",
            "icon":"http://d1594bg0curop3.cloudfront.net/img_mywind_news_white.png",
            "inbound":true,
            "receiptData":"{\"campaignId\":1091,\"collateralCode\":\"1000m6gnv77b\",\"campaignCode\":\"1000m6gnt873\",\"msisdn\":\"00393200106398\",\"newsId\":84,\"channel\":\"inbound_trm_news\"}"
        }
    ]
}

GET /details

Get news details by news id.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

id

Y

id of news

msisdn

Y

active msisdn

If offer not found or already activated, backend will return custom error:

{
    "error": true,
    "status": 400,
    "code": "ALREADY_ACTIVATED"
}

See sample response below. Note that receiptData is a stringified JSON. Application should not use any data from receiptData, but pass it AS IS to backend in all further /receipt requests

{
"success":true,
"status":200,
"news":{
    "id":218,
    "campaignCode":"1000mfjgrptx",
    "category":"21366",
    "created_at":1580468840000,
    "updated_at":1580480680000,
    "title":"MIA 100 - Digital S",
    "short_description":"MIA 100 - Digital",
    "long_description":"MIA 100>",
    "id_manuale":null,
    "cta_visibility":"1",
    "cta_manual_label":"SCOPRI",
    "cta_action":"OFFERTA",
    "cta_manual_param":"ROPZ4737_POPZ001514",
    "section":"",
    "image_url":"http://d1594bg0curop3.cloudfront.net/MIA_100_digital_S.jpg",
    "image_desc":"",
    "icon":"http://d1594bg0curop3.cloudfront.net/img_mywind_news_white.png",
    "inbound":true,
    "receiptData":"{\"campaignId\":1248,\"collateralCode\":\"1000mfjgss4f\",\"campaignCode\":\"1000mfjgrptx\",\"msisdn\":\"00393341234567\",\"newsId\":218,\"channel\":\"trm_news\"}"
}
}

GET /msisdn

Returns the list of msisdn associated with Campaign by campaignId.

Argument

Required

Description

nid

Y

unique device identifier

bundle

Y

e.g. “it.wind.myWind”

campaignId

Y

Integer ID of the campaign

Expected response: {"success": true, "status": 200, "msisdn": ['333xxxxxxx', '334yyyyyyy']}