API de Geozones

getNearestZone

Chamado internamente pelo SDK. Recupera os parâmetros da geozone mais próxima e a distância até ela. Também registra a localização do dispositivo para notificações push geográficas.

POST https://api.pushwoosh.com/json/1.3/getNearestZone

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
application	`string`	Sim	código do aplicativo Pushwoosh
hwid	`string`	Sim	ID de hardware do dispositivo usado na solicitação `/registerDevice`.
lat	`string`	Sim	Latitude do dispositivo.
lng	`string`	Sim	Longitude do dispositivo.

Exemplo de solicitação

{
  "request": {
    "application": "APPLICATION_CODE",
    "hwid": "HWID",
    "lat": 10.12345,
    "lng": 28.12345
  }
}

Exemplo em PHP

// Veja http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html

use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;

// Cria a instância da solicitação
$request = GetNearestZoneRequest::create()
    ->setHwid('HWID')
    ->setLat(10.12345)
    ->setLng(28.12345);

// Chama o Web Service '/getNearestZone'
$response = $pushwoosh->getNearestZone($request);

if ($response->isOk()) {
    print 'Zone name : ' . $response->getResponse()->getName();
    print 'Latitude : ' . $response->getResponse()->getLat();
    print 'Longitude : ' . $response->getResponse()->getLng();
    print 'Range : ' . $response->getResponse()->getRange();
    print 'Distance : ' . $response->getResponse()->getDistance();
} else {
    print 'Oops, the operation failed :-(';
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

addGeoZone

Adiciona uma Geozone a um aplicativo específico.

POST https://api.pushwoosh.com/json/1.3/addGeoZone

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
application	`string`	Sim	código do aplicativo Pushwoosh
geozones	`array`	Sim	Parâmetros da Geozone como um array JSON.
geozones.name	`string`	Sim	Nome da Geozone.
geozones.lat	`string`	Obrigatório para um círculo.	Latitude da Geozone. Omita quando `polygon` estiver definido — uma geozone poligonal deriva seu próprio centro.
geozones.lng	`string`	Obrigatório para um círculo.	Longitude da Geozone. Omita quando `polygon` estiver definido — uma geozone poligonal deriva seu próprio centro.
geozones.cooldown	`integer`	Sim	Período de silêncio após o envio de uma notificação (em segundos).
geozones.range	`integer`	Obrigatório para um círculo.	Alcance da Geozone em metros. Mínimo 50. Omita quando `polygon` estiver definido — uma geozone poligonal deriva seu próprio alcance.
geozones.polygon	`object`	Não	Torna a geozone um polígono em vez de um círculo. Não pode ser combinado com `lat`/`lng`/`range` — o envio de ambos é rejeitado. Veja Geozones poligonais.
geozones.content	`string ou object`	Obrigatório se `presetCode` estiver vazio.	Conteúdo da mensagem da Geozone.
geozones.presetCode	`string`	Obrigatório se `content` estiver vazio.	Preset de Push para usar em vez de `content`.
geozones.cluster	`string`	Não	Especifique `null` para desvincular um cluster da Geozone.
geozones.campaign	`string`	Não	Especifique `null` para desvincular uma campanha da Geozone. Se omitido, o valor da campanha permanece inalterado. Nota: Tem prioridade maior que a campanha no preset.
geozones.timetable	`object`	Não	Define os intervalos do cronograma.

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // token de acesso à API do Painel de Controle Pushwoosh
    "application": "XXXXX-XXXXX",            // código do aplicativo Pushwoosh
    "geozones": [{
      "name": "Statue of George",            // obrigatório. Nome da Geozone.
      "lat": "40.70087797",                   // obrigatório. Latitude da Geozone.
      "lng": "-73.931851387",                 // obrigatório. Longitude da Geozone.
      "cooldown": 60,                         // em segundos, obrigatório. Período de silêncio após o envio de uma notificação
      "range": 50,                            // em metros, mínimo 50, obrigatório. Alcance da geozone.
      "content": "Lorem ipsum dolor sit amet,
       consectetur adipiscing elit.",         // ou objeto
      "presetCode": "AAAAA-BBBBB",            // opcional. O preset de Push pode ser usado em vez do conteúdo
      "cluster": "GEOZONE CLUSTER CODE",      // opcional. O período de cooldown do cluster será aplicado
      "campaign": "CAMPAIGN_CODE",            // opcional. Especifique null para desvincular a Campanha da Geozone
      "timetable": {                          // opcional
        "timezone": 1234,                     // em segundos
        "Mon": [                              // dias disponíveis: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Envio de Push
          {
            "start": "04:11",
            "stop": "12:00"
          }
        ],
        "Sun": [
          {                                    // um ou dois intervalos
            "start": "01:11",
            "stop": "17:00"
          },
          {
            "start": "18:01",
            "stop": "23:59"
          }
        ]
      }
    }]
  }
}

Adicionando várias geozones de uma vez

geozones aceita um array, então uma chamada pode criar um lote inteiro. O lote é validado como um todo antes que qualquer coisa seja escrita: se alguma entrada for rejeitada, a chamada falha e nenhuma geozone daquela solicitação é criada. O erro nomeia a entrada ofensiva por sua posição no array, contada a partir de zero:

{
  "status_code": 210,
  "status_message": "geozones[301]: range: range must be at least 50 meters"
}

Corrija essa entrada e envie a solicitação novamente. Em caso de sucesso, GeoZones contém os novos IDs numéricos na mesma ordem das entradas que você enviou.

Lotes maiores que 500 entradas são aceitos e divididos em partes internamente. O array inteiro ainda é validado antes da primeira escrita, mas a escrita em si não é atômica entre as partes: uma entrada pode passar na validação e ainda assim falhar ao ser escrita, por exemplo, se o preset que ela nomeia for excluído nesse meio tempo. Nesse caso, a chamada retorna 200 com os IDs que foram escritos mais um array Errors nomeando a entrada que interrompeu a execução, para que nada criado seja perdido:

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "GeoZones": [100016750, 100016751],
    "Errors": [{ "index": 2, "message": "preset not found" }]
  }
}

Errors está ausente quando todas as entradas foram escritas, então uma resposta totalmente bem-sucedida não é alterada. Um array GeoZones mais curto que o array que você enviou sempre significa que algumas entradas não foram criadas.

Geozones poligonais

Envie polygon em vez de lat/lng/range para tornar a geozone um polígono. polygon.vertices é um anel ordenado de pontos {lat, lng} que descrevem o contorno da forma:

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",
    "application": "XXXXX-XXXXX",
    "geozones": [{
      "name": "Downtown mall — ground floor",
      "cooldown": 60,
      "polygon": {
        "vertices": [
          { "lat": 40.70087797, "lng": -73.931851387 },
          { "lat": 40.70112456, "lng": -73.931602211 },
          { "lat": 40.70095321, "lng": -73.930987654 },
          { "lat": 40.70068912, "lng": -73.931233456 }
        ]
      },
      "content": "Welcome! Enjoy 15% off your first purchase today."
    }]
  }
}

lat, lng e range são derivados do anel — o círculo que um dispositivo realmente monitora é centrado na forma com um raio que atinge seu vértice mais distante (mínimo de 50 m). Enviar polygon junto com lat/lng/range é rejeitado.

Você pode enviar o anel aberto ou fechado — se o último vértice repetir o primeiro, o servidor descarta essa duplicata de fechamento antes de validar. Validação de vértices, no anel resultante: 3 a 100 vértices distintos. O anel também é rejeitado se seus pontos forem colineares, se suas arestas se auto-interceptarem ou se cruzar o antimeridiano.

updateGeoZone

Atualiza as propriedades da Geozone.

POST https://api.pushwoosh.com/json/1.3/updateGeoZone

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
geoZoneId	`string`	Sim	ID da Geozone da solicitação `/addGeoZone`.
name	`string`	Não	Novo nome da Geozone.
cooldown	`integer`	Não	Cooldown para atualizar, em segundos.
status	`integer`	Não	0 - desativado, 1 - ativado.
content	`string`	Não	Conteúdo para a notificação push da Geozone. Não pode ser usado com `presetCode`.
cluster	`string`	Não	Novo nome do cluster. Especifique `null` para desvincular o cluster da Geozone.
campaign	`string`	Não	Novo ID da campanha. Especifique `null` para desvincular a Campanha da Geozone. Se omitido, o valor da Campanha não será alterado. Tem prioridade maior que uma Campanha de um preset.
lat	`number`	Não	Latitude da Geozone. Não pode ser combinado com `polygon`.
lng	`number`	Não	Longitude da Geozone. Não pode ser combinado com `polygon`.
range	`integer`	Não	Novo alcance em metros. Não pode ser combinado com `polygon`.
polygon	`object`	Não	Novo anel de vértices `{lat, lng}` — substitui a forma e re-deriva `lat`/`lng`/`range` a partir dele. Veja Geozones poligonais. Funciona de ambas as formas: envie-o em uma geozone circular existente para transformá-la em um polígono, ou envie um anel vazio (`{"vertices": []}`) em uma geozone poligonal existente para transformá-la de volta em um círculo. Omita `polygon` completamente para deixar a forma inalterada. Mesma validação de vértices que `addGeoZone`.
timetable	`object`	Não	Cronograma da Geozone. Veja mais informações abaixo.

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // obrigatório, token de acesso à API do Controle Pushwoosh
    "geoZoneId": 100016750,                  // obrigatório, do método /addGeoZone
    "name": "new geozone name",              // opcional
    "cooldown": 222,                         // em segundos, opcional
    "status": 0,                             // opcional, 0 - desativado, 1 - ativado
    "presetCode": "BBBBB-AAAAA",             // opcional, não pode ser usado junto com "content"
    "content": "new geozone content",        // opcional, não pode ser usado junto com "presetCode"
    "cluster": "GEOZONE CLUSTER CODE",       // opcional. Especifique null para desvincular o cluster da Geozone
    "campaign": "CAMPAIGN_CODE",             // opcional. Especifique null para desvincular a Campanha da Geozone
    "lat": 10.56,                            // opcional, latitude da geozone
    "lng": 12.523,                           // opcional, longitude da geozone
    "range": 500,                            // opcional, alcance da geozone
    "timetable": {                           // opcional
      "timezone": 1234,                      // em segundos
      "Mon": [                               // dias disponíveis: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Envio de Push
        {
          "start": "04:11",
          "stop": "12:00"
        }
      ],
      "Sun": [
        {                                    // um ou dois intervalos
          "start": "01:11",
          "stop": "17:00"
        },
        {
          "start": "18:01",
          "stop": "23:59"
        }
      ]
    }
  }
}

deleteGeoZone

Remove Geozones do aplicativo.

POST https://api.pushwoosh.com/json/1.3/deleteGeoZone

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
application	`string`	Sim	código do aplicativo Pushwoosh
geozones	`string`	Sim	Array de IDs ou um ID único de uma Geozone para remover.

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // obrigatório, token de acesso à API do Controle Pushwoosh
    "application": "XXXXX-XXXXX",            // obrigatório, código do aplicativo Pushwoosh
    "geozones": [550, 526]                   // obrigatório, IDs das geozones
  }
}

addGeoZoneCluster

Adiciona um Cluster de Geozone ao aplicativo.

POST https://api.pushwoosh.com/json/1.3/addGeoZoneCluster

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
application	`string`	Sim	código do aplicativo Pushwoosh
name	`string`	Sim	Nome do cluster.
cooldown	`integer`	Sim	Um atraso antes que um único usuário possa receber a mesma mensagem do Cluster de Geozone, em segundos.

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // obrigatório, token de acesso à API do Controle Pushwoosh
    "application": "XXXXX-XXXXX",            // obrigatório, código do aplicativo Pushwoosh
    "name": "Raccoon city",                  // obrigatório, nome do cluster
    "cooldown": 3210                         // obrigatório, em segundos
  }
}

deleteGeoZoneCluster

Remove um Cluster de Geozone do aplicativo.

POST https://api.pushwoosh.com/json/1.3/deleteGeoZoneCluster

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
application	`string`	Sim	código do aplicativo Pushwoosh
geoZoneCluster	`string`	Sim	ID do cluster de Geozone a ser removido.

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // obrigatório, token de acesso à API do Controle Pushwoosh
    "application": "XXXXX-XXXXX",            // obrigatório, código do aplicativo Pushwoosh
    "geoZoneCluster": "EA1CE-69405"          // obrigatório, ID do cluster obtido da solicitação /addGeoZoneCluster
  }
}

listGeoZones

Recupera uma lista de Geozones para o aplicativo.

POST https://api.pushwoosh.com/json/1.3/listGeoZones

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
application	`string`	Sim	código do aplicativo Pushwoosh

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // obrigatório, token de acesso à API do Controle Pushwoosh
    "application": "XXXXX-XXXXX"             // obrigatório, código do aplicativo Pushwoosh
  }
}

listGeoZoneClusters

Recupera uma lista de clusters de Geozone para o aplicativo.

POST https://api.pushwoosh.com/json/1.3/listGeoZoneClusters

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
auth	`string`	Sim	token de acesso à API do Painel de Controle Pushwoosh.
application	`string`	Sim	código do aplicativo Pushwoosh

Exemplo de solicitação

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // obrigatório, token de acesso à API do Controle Pushwoosh
    "application": "XXXXX-XXXXX"             // obrigatório, código do aplicativo Pushwoosh
  }
}