API de resultados de desafios

Portais de marca branca e outras integrações compatíveis podem criar uma experiência de resultados de desafios com os endpoints abaixo. Todos usam o código do desafio e exigem uma solicitação de API autenticada.

/api/v1/gamification/challenge/{code}/

Sequência de endpoints #

Comece com result-settings/. Use suas flags e descrições de colunas para decidir quais controles e telas devem ser renderizados, em vez de pressupor que todos os desafios tenham o mesmo formato de resultados.

Obtenha os valores de challenger_id na classificação paginada results/ do desafio. Os IDs das atividades vêm da lista aninhada activities.results na resposta detalhada.

Configurações dos resultados #

GET /api/v1/gamification/challenge/{code}/result-settings/

A resposta descreve a apresentação atual dos resultados do desafio:

• primary_column e ordered_by identificam a métrica da classificação e a ordem padrão.
• columns e team_columns são descritores ordenados de renderização; suas chaves correspondem aos campos das linhas de classificação dos participantes e das equipes.
• totals, progress, sections, distances e participant_data fornecem contexto opcional para todo o desafio.
• show_map e show_heatmap informam ao cliente quais visualizações de mapa oferecer. show_analytics indica se o solicitante pode ver os dados fisiológicos das atividades de outro participante; não restringe as análises acessíveis do próprio solicitante.
• results_limited é null quando não há restrições. Um número significa que o solicitante só pode ver essa quantidade de linhas no topo e que os controles de filtragem, ordenação e paginação dos resultados devem ser ocultados.

Esses valores consideram o solicitante. Por exemplo, o mesmo desafio pode retornar configurações sem restrições para um participante e configurações limitadas para um usuário conectado que não participa.

Mapa de calor dos treinos #

GET /api/v1/gamification/challenge/{code}/heatmap/

O mapa de calor agrega as atividades GPS aceitas em células de uma grade de aproximadamente 150 metros. Cada célula é [longitude, latitude, weight], em que o peso corresponde ao número de atividades distintas que passaram por ela. Uma atividade contribui no máximo uma vez para cada célula, e treinos marcados como privados no aplicativo de origem são excluídos.

Os mapas de calor são gerados sob demanda. Quando não há um mapa armazenado, a primeira solicitação inicia a geração em segundo plano e retorna:

{"status": "pending"}

Consulte novamente após alguns segundos. Uma resposta pronta contém generated_at, cell_size, activity_count, max_weight, truncated e cells. Os dados armazenados podem continuar sendo servidos enquanto um mapa desatualizado é atualizado em segundo plano.

Use max_weight para normalizar uma camada de densidade ponderada. Se truncated for true, a resposta conterá as células com maior peso, em vez de todas as células geradas.

O endpoint retorna 404 quando o organizador não habilitou show_heatmap, durante uma janela de resultados ocultos ou quando os resultados públicos estão restritos e o solicitante não é participante.

Resultado detalhado do participante #

GET /api/v1/gamification/challenge/{code}/results/{challenger_id}/detailed/

A resposta combina:

• A linha de classificação do participante, a distância escolhida, a colocação e result_rank_total.
• statistics, como distância, duração, ritmo ou velocidade, energia, passos, número de atividades, dias ativos, maior sequência e frequência cardíaca média, quando disponível.
• is_own_result, que identifica se a linha pertence ao participante autenticado.
• head_to_head, disponível apenas quando um participante visualiza seu próprio resultado. Inclui colocação e percentil, métrica da classificação, diferenças para concorrentes próximos e para o líder, média do grupo e linhas do pódio.
• activities, uma lista aninhada e paginada de atividades aceitas e visíveis creditadas ao resultado. Cada linha inclui metadados básicos do treino, ritmo médio, uma forma de rota quando disponível e has_analytics.

Para um resultado de distância fixa, a lista de atividades termina na atividade que concluiu a distância selecionada. As atividades posteriores não aparecem porque não contribuíram para esse resultado.

Paginação aninhada das atividades #

A lista de atividades tem os campos habituais count, next, previous e results, mas usa parâmetros de consulta próprios para não entrar em conflito com a paginação de nível superior:

Formas de rota sem localização #

As rotas na linha do tempo das atividades não são coordenadas geográficas. O servidor desloca e redimensiona cada trajeto GPS para um espaço fixo de coordenadas SVG de 158 × 108 e retorna apenas:

• path — dados do caminho SVG
• start e end — pontos no espaço de coordenadas normalizado
• point_count — número de pontos na forma retornada

Latitude e longitude absolutas, limites e centro não são incluídos. A mesma rota deslocada para outro local gera a mesma forma; portanto, ela é adequada para uma miniatura, mas não pode ser traçada em um mapa geográfico.

Análises por atividade #

GET /api/v1/gamification/challenge/{code}/results/{challenger_id}/activities/{activity_id}/analytics/

A atividade deve estar aceita, visível e associada exatamente ao resultado desse participante. A resposta contém distância, duração, ritmo e velocidade básicos, além de todas as análises que podem ser derivadas dos fluxos armazenados:

Cada bloco pode ser null independentemente dos demais, pois provedores e dispositivos fornecem fluxos diferentes. has_streams indica se há análises utilizáveis de fluxos. x_kind identifica se os valores x do gráfico representam a distância acumulada ou o tempo decorrido.

Os blocos de baixa sensibilidade — forma de rota, parciais, ritmo e elevação — estão disponíveis para qualquer solicitante que possa acessar o resultado. Os blocos fisiológicos — frequência cardíaca, zonas, cadência e esforço — estão sempre disponíveis para o resultado acessível do próprio solicitante. Para a atividade de outro participante, eles só são retornados quando o organizador habilitou show_analytics e o solicitante cumpre as regras de visibilidade dos resultados. Caso contrário, esses blocos são null e physio_restricted é true.

Regras de visibilidade e privacidade #

Os participantes do desafio mantêm acesso aos resultados completos fora de uma janela de resultados ocultos. O acesso da equipe da organização pode diferir do acesso dos participantes, mas os clientes ainda devem seguir os valores específicos do solicitante retornados por result-settings/.

Relacionados #

• Visão geral da API pública
• Configuração de marca branca e empresarial