API iFrame · Ajuda do Measure Map Online

Mostre um dos seus projetos como um mapa ao vivo no seu próprio site, nas unidades, no estilo de mapa e no tema que convêm ao seu site.

A API iFrame coloca o mapa de um projeto na sua própria página web. Os visitantes veem o mapa de satélite com as suas medições e podem deslocar-se nele, sem conta e sem sair do seu site. Escolhe o projeto, as unidades, o estilo do mapa e o tema de cores.

Antes de começar#

Uma chave de API de produção com acesso Mapas incorporados. Consulte chaves de API.
Um projeto que os visitantes possam ver. Defina o seu nível de acesso como Somente visualização ou Público. Um projeto Privado não abre para visitantes sem conta. Consulte que projetos podem ser incorporados.
Opcionalmente, restrições de sites na chave, para que a incorporação só funcione nos seus próprios sites. Consulte chaves de API.

Gerar o código de incorporação#

Developer > Incorporar um mapa gera o código por si com a sua chave de produção: escolha o projeto, o tema, as unidades, o tipo de mapa e o tamanho, verifique a Pré-visualização ao vivo e copie o Código de incorporação. Se o projeto for privado, a secção indica-o e oferece Mudar para «Somente visualização». Consulte obter o código de incorporação para cada passo.

Incorporar um mapa com um projeto escolhido e a pré-visualização ao vivo

O código leva a sua chave, por isso continua a funcionar até substituir a chave. A secção avisa-o quando a chave pode fazer mais do que Mapas incorporados, já que qualquer pessoa a pode ler no código-fonte da sua página, e quando a chave não tem restrições de sites. Só a Pré-visualização ao vivo usa um token de curta duração. Consulte chave ou token.

O endereço de incorporação#

Uma incorporação é um <iframe> cujo endereço começa por https://app.measuremaponline.com/iframe_api, seguido destes parâmetros:

Parâmetro	Necessário	Valores
`pid`	obrigatório	O identificador do projeto: a parte depois de `/p/` no endereço do projeto na aplicação.
`key`	`key` ou `token`	A sua chave de API.
`token`	`key` ou `token`	Um token do seu servidor (ver abaixo).
`ms`	opcional	Unidades: `metric` ou `imperial`. Sem ele, os visitantes nos Estados Unidos veem unidades imperiais e todos os outros métricas.
`maptype`	opcional	`satellite` (a predefinição), `map`, `hybrid` ou `terrain`.
`theme`	opcional	`auto` (a predefinição: segue a definição do sistema do visitante), `light` ou `dark`.

Um exemplo mínimo#

<iframe src="https://app.measuremaponline.com/iframe_api?pid=YOUR_PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="YOUR_PROJECT_NAME" width="500" height="500" style="border:0" allow="fullscreen"></iframe>

Substitua YOUR_PROJECT_ID, YOUR_API_KEY e YOUR_PROJECT_NAME (os leitores de ecrã leem o title em voz alta), e defina a largura e a altura adequadas à sua página.

O código de incorporação com o seu botão de copiar

Chave ou token#

Com key, como no código que a secção Incorporar um mapa lhe dá, a incorporação continua a funcionar enquanto a chave funcionar, nos sites que as suas restrições permitem. A sua chave fica então visível no código-fonte da sua página, por isso:

use uma chave só com acesso Mapas incorporados;
restrinja-a aos seus próprios sites;
quando substituir a chave, atualize as suas páginas nas 24 horas em que a chave antiga continua a funcionar.

Com token, a chave fica no seu servidor. Serve para incorporações que o seu próprio servidor escreve na página em cada visita: antes de mostrar a página, pede um token à API REST e coloca-o no endereço do iframe:

POST https://api.measuremaponline.com/api/v2/auth/iframe/token, com a sua chave no cabeçalho Authorization, devolve um token que funciona durante 60 minutos;
POST https://api.measuremaponline.com/api/v2/auth/token faz o mesmo e aceita uma duration em segundos, até 24 horas. A resposta indica quando o token expira.

A sua conta pode obter até 600 tokens por hora. Use uma chave de produção: as incorporações só mostram projetos de produção, por isso um token criado com uma chave de testes não abre nenhum mapa. Consulte a referência da API.

O que os visitantes podem fazer#

Os visitantes podem deslocar e aproximar o mapa e ler as medições das suas formas. Não podem alterar nada: a edição está desativada dentro de uma incorporação, seja qual for o nível de acesso do projeto. A única exceção é um projeto do Open Guest no plano Open Guest, onde os visitantes medem por si próprios.

Quando o mapa não aparece#

Verifique, por esta ordem:

O endereço tem um token que expirou. Os tokens duram 60 minutos, a menos que o seu servidor tenha pedido mais tempo. Copie de novo o código de Incorporar um mapa, que usa a sua chave, ou faça com que o seu servidor obtenha um token novo em cada visita (consulte acima).
O projeto é privado. Defina-o como Somente visualização ou Público, ou prima Mudar para «Somente visualização» em Incorporar um mapa.
O site não está autorizado. Se a chave tiver restrições de sites, a página que mostra a incorporação tem de estar num deles. Alguns navegadores e sites ocultam a página em que está uma incorporação; com restrições definidas, essa incorporação é recusada.
A chave foi substituída. Uma chave antiga deixa de funcionar 24 horas depois de ser criada uma nova, ou de imediato se tiver sido revogada.
A chave é de testes. As incorporações só funcionam com chaves e projetos de produção.
A subscrição não está ativa, ou o acesso à API foi suspenso: a secção Chaves de API indica-o.