Ligar o XREAL Aura aos sistemas da sua empresa

Ligar o XREAL Aura aos sistemas da sua empresa

Resumo executivo

Para ligar o XREAL Aura a um sistema empresarial, execute uma aplicação autorizada da empresa no respetivo compute puck com Android XR e deixe que essa aplicação solicite dados à API do sistema. Uma API é uma ligação de software que permite a uma aplicação obter informações de outra. Este guia cria uma pequena aplicação que obtém uma ordem de trabalho e apresenta as respetivas instruções no Aura.

Uma ordem de trabalho de manutenção é uma boa primeira integração, porque combina um número de registo, detalhes do equipamento e instruções práticas. A aplicação obtém esses campos através de uma ligação autorizada e apresenta-os numa janela legível. A mesma abordagem pode ser adaptada a outros registos empresariais, quando as respetivas API e regras de acesso o permitirem.

Como funciona a integração empresarial do XREAL Aura

O XREAL Aura utiliza óculos com cabo e um compute puck, o pequeno computador que executa o Android XR e a sua aplicação. A aplicação liga-se ao sistema da empresa através de Wi-Fi e de uma rota de rede aprovada; os óculos mostram as informações devolvidas. [1]

Uma ordem de trabalho descreve uma tarefa e as instruções para a realizar. Um colaborador introduz o número da ordem na aplicação do Aura e seleciona Load work order. A aplicação solicita esse registo ao sistema empresarial e mostra depois o nome do equipamento, a versão do procedimento e as instruções detalhadas. Os botões Next e Previous permitem ao colaborador percorrer as instruções, enquanto o registo de origem permanece inalterado.

Se a sua empresa já tem uma aplicação Android que apresenta estes registos, peça ao respetivo programador que verifique se funciona corretamente no Android XR antes de criar outra. A Google suporta interfaces Android padrão (como uma aplicação Android 2D para telemóvel ou para ecrã grande) apresentadas num painel de sistema XR, sob a forma de uma janela 2D mostrada dentro do ambiente XR. Uma aplicação existente continua a precisar de testes de compatibilidade e de acesso. [4]

Para contexto sobre o hardware, consulte a nossa página de produto do XREAL Aura. Confirme a disponibilidade e o suporte atuais no seu país, uma vez que as informações de lançamento mudam. [2]

Passo 1 Obtenha uma ordem de trabalho de teste e os respetivos dados de ligação

A sua aplicação do Aura precisa de um registo para apresentar e de permissão para o obter do sistema da empresa. Uma ordem de trabalho é um registo de tarefa que contém um número de ordem, detalhes do equipamento e instruções, como os passos para inspecionar uma máquina.

· Antes de escrever o código, certifique-se de que tem um endpoint HTTPS, um token de acesso de teste e um número de ordem de trabalho de exemplo (por exemplo, WO-1001) que corresponda ao esquema JSON da Referência para programadores.

· Peça à sua equipa de TI o endereço da API que obtém esta ordem e um token de acesso de teste temporário. O endereço da API indica à aplicação onde solicitar o registo; o token dá-lhe permissão para ler os dados. Peça à equipa de TI que confirme que ambos funcionam e se é necessário acesso à rede da empresa.

· Partilhe com a equipa de TI a Referência para programadores que se encontra no final deste artigo, para que possam verificar se os dados devolvidos correspondem à aplicação de exemplo. Se forem diferentes, atualize o código no Passo 3 para ler os nomes dos campos do seu sistema. Se não existir uma API adequada, a equipa de TI terá primeiro de disponibilizar uma.

Tenha estes três elementos à mão: o endereço da API entra no código no Passo 3; o token e o número da ordem de trabalho são introduzidos na aplicação em execução no Passo 4. Em conjunto, permitem à aplicação obter a tarefa e apresentar as respetivas instruções no Aura.

Passo 2 Abra o Android Studio e prepare a aplicação

Passo 2.1 Crie o projeto no seu computador

· No browser do seu computador, abra a página oficial de transferência do Android Studio. Instale o Android Studio e conclua a configuração. Se precisar das ferramentas XR dedicadas da Google, siga o guia de configuração do Android Studio para XR, que atualmente recomenda uma versão Canary, uma versão de desenvolvimento preliminar. [5]

· Abra o Android Studio. No ecrã de boas-vindas, selecione New Project. Se outro projeto estiver aberto, selecione File > New > New Project no menu superior do Android Studio.

· Na janela do projeto, selecione Phone and Tablet > Empty Activity. Selecione Next.

· Defina Name como AuraWorkOrders e Package name como com.example.auraworkorders. Utilize Kotlin quando surgir uma opção de linguagem, mantenha as definições de SDK do modelo e selecione Finish.

· Aguarde até que o Android Studio conclua a sincronização do Gradle. O Gradle é a ferramenta de compilação que prepara as bibliotecas e as definições do projeto. Resolva quaisquer erros na janela Build ou Sync antes de continuar.

Passo 2.2 Permita que a aplicação aceda à rede

O manifesto é o ficheiro Android que declara aquilo de que a aplicação precisa, incluindo a permissão de rede.

· No painel Project, à esquerda no Android Studio, selecione a vista Android no menu pendente. Se o painel estiver oculto, selecione View > Tool Windows > Project.

· Nesse painel, expanda app > manifests e abra AndroidManifest.xml.

· Dentro do elemento manifest, acima do elemento application, adicione esta linha. Mantenha o resto do ficheiro gerado.

<uses-permission android:name="android.permission.INTERNET" />

· No mesmo ficheiro, localize a tag de abertura application. Adicione android:usesCleartextTraffic="false" como atributo dentro dessa tag. O Android já bloqueia HTTP não encriptado nas aplicações destinadas ao Android 9 ou posterior, pelo que esta linha torna a intenção explícita.

A permissão INTERNET é concedida durante a instalação; não gera nenhum pedido de acesso quando a aplicação é executada. [6] O exemplo utiliza as ferramentas de rede e de JSON integradas no Android, pelo que não precisa de adicionar o Retrofit nem outra biblioteca de rede.

Passo 3 Adicione o código que obtém e apresenta a ordem de trabalho

Este código liga a aplicação ao endereço do Passo 1, lê a resposta e apresenta uma instrução de cada vez. O pedido de rede é executado separadamente da interface, para que o ecrã continue a responder.

Passo 3.1 Abra o ficheiro correto no Android Studio

· No painel Project, à esquerda no Android Studio, expanda app > kotlin+java > com.example.auraworkorders. Algumas versões designam a pasta de código-fonte como java.

· Abra MainActivity.kt. Este ficheiro controla o ecrã inicial da aplicação.

· Substitua o conteúdo pelo código abaixo. Se o nome do seu pacote for diferente, altere a primeira linha para corresponder ao pacote que criou no Passo 2.

package com.example.auraworkorders
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp
import org.json.JSONObject
import java.net.URL
import java.util.concurrent.Executors
import javax.net.ssl.HttpsURLConnection
data class WorkStep(
    val number: Int, val title: String,
    val instruction: String, val expectedResult: String
)
data class WorkOrder(
    val id: String, val asset: String,
    val revision: String, val steps: List<WorkStep>
)
fun fetchOrder(id: String, token: String): WorkOrder {
    require(Regex("[A-Za-z0-9-]{1,40}").matches(id))
    // Replace only this origin with your approved API origin.
    val url = URL("https://api.your-company.example/work-orders/$id")
    val c = url.openConnection() as HttpsURLConnection
    try {
    	c.requestMethod = "GET"
    	c.instanceFollowRedirects = false
    	c.connectTimeout = 10000
    	c.readTimeout = 10000
        c.setRequestProperty("Authorization", "Bearer $token")
        c.setRequestProperty("Accept", "application/json")
    	val status = c.responseCode
    	check(status == 200) { "HTTP $status" }
    	val text = c.inputStream.bufferedReader().use { it.readText() }
    	val obj = JSONObject(text)
    	check(obj.getString("id") == id) { "Order ID mismatch" }
    	val array = obj.getJSONArray("steps")
    	check(array.length() > 0) { "No instructions available" }
    	val steps = (0 until array.length()).map { index ->
        	val s = array.getJSONObject(index)
            WorkStep(s.getInt("number"), s.getString("title"),
                s.getString("instruction"), s.getString("expectedResult"))
    	}.sortedBy { it.number }
    	return WorkOrder(obj.getString("id"), obj.getString("asset"),
            obj.getString("revision"), steps)
    } finally {
    	c.disconnect()
    }
}
class MainActivity : ComponentActivity() {
    private val worker = Executors.newSingleThreadExecutor()
    override fun onCreate(savedInstanceState: Bundle?) {
    	super.onCreate(savedInstanceState)
    	setContent {
        	MaterialTheme {
            	WorkOrderScreen { id, token, done ->
                	worker.execute {
                    	val result = runCatching { fetchOrder(id, token) }
                    	runOnUiThread {
                        	if (!isDestroyed) done(result)
                    	}
                	}
            	}
        	}
    	}
    }
    override fun onDestroy() {
    	worker.shutdownNow()
    	super.onDestroy()
    }
}
@Composable
fun WorkOrderScreen(
    load: (String, String, (Result<WorkOrder>) -> Unit) -> Unit
) {
    var id by remember { mutableStateOf("WO-1001") }
    var token by remember { mutableStateOf("") }
    var order by remember { mutableStateOf<WorkOrder?>(null) }
    var index by remember { mutableStateOf(0) }
    var busy by remember { mutableStateOf(false) }
    var message by remember { mutableStateOf("Enter test credentials.") }
    Surface(Modifier.fillMaxSize()) {
    	Column(Modifier.padding(24.dp)
            .verticalScroll(rememberScrollState()),
        	verticalArrangement = Arrangement.spacedBy(16.dp)) {
        	Text("Work instructions", style = MaterialTheme.typography.headlineMedium)
        	OutlinedTextField(value = id, onValueChange = { id = it },
            	label = { Text("Work order ID") },
            	singleLine = true, enabled = !busy)
        	OutlinedTextField(value = token, onValueChange = { token = it },
            	label = { Text("Sandbox access token") }, singleLine = true,
            	visualTransformation = PasswordVisualTransformation(),
            	enabled = !busy)
        	Button(enabled = !busy && token.isNotBlank() &&
                Regex("[A-Za-z0-9-]{1,40}").matches(id), onClick = {
            	busy = true
            	order = null
            	index = 0
            	message = "Loading work order..."
            	load(id, token) { result ->
                	busy = false
                	result.onSuccess {
                    	order = it
                    	message = "Read-only instructions loaded."
                	}.onFailure {
                    	message = "Could not load order. Check access and network."
                	}
            	}
        	}) { Text(if (busy) "Loading..." else "Load work order") }
        	Text(message)
        	order?.let { current ->
            	Text("${current.id} | ${current.asset}")
            	Text("Procedure revision ${current.revision}")
            	val step = current.steps[index]
            	Text("Step ${index + 1} of ${current.steps.size}",
                	style = MaterialTheme.typography.titleLarge)
            	Text(step.title, style = MaterialTheme.typography.headlineSmall)
            	Text(step.instruction, style = MaterialTheme.typography.bodyLarge)
            	Text("Expected result: ${step.expectedResult}")
            	Row(horizontalArrangement = Arrangement.spacedBy(16.dp)) {
                	Button(enabled = index > 0,
                    	onClick = { index-- }) { Text("Previous") }
                	Button(enabled = index < current.steps.lastIndex,
                    	onClick = { index++ }) { Text("Next") }
            	}
            	Text("Navigation does not record task completion.")
        	}
    	}
    }
}

Passo 3.2 Introduza o endereço da API da sua empresa

· Permaneça em MainActivity.kt no Android Studio. Prima Ctrl+F no Windows ou Linux, ou Command+F no macOS, e procure api.your-company.example.

· Substitua o URL de exemplo na linha URL(...) pelo padrão de endpoint da sua empresa obtido no Passo 1. Mantenha $id no local onde deve ficar o número da ordem de trabalho. Por exemplo, se o servidor esperar /api/jobs/WO-1001, o código deve solicitar https://YOUR-APPROVED-HOST/api/jobs/$id .· Não coloque o token neste ficheiro. A aplicação disponibiliza um campo de teste temporário para o introduzir quando a executar.

· Se a resposta da sua API for diferente da Referência para programadores, atualize os nomes dos campos e a estrutura lidos por fetchOrder antes de executar. Nesta função, JSONObject lê a resposta e getJSONArray("steps") abre a respetiva lista de instruções.

· No Android Studio, selecione Build > Make Project, se esse comando estiver disponível na sua versão, ou utilize o botão Run da barra de ferramentas no Passo 4 para compilar o projeto. Corrija quaisquer erros de compilação na janela Build.

Resultado esperado: o projeto é compilado e o URL em MainActivity.kt aponta para o seu serviço de teste real. O endereço de exemplo terminado em .example não se ligará a nenhum sistema empresarial.

Passo 4 Teste a ligação no seu computador

Um emulador é um dispositivo Android virtual apresentado no seu computador. Utilize-o primeiro para verificar o endereço da API, o token e as instruções devolvidas, antes de resolver problemas num dispositivo físico.

Passo 4.1 Inicie a aplicação a partir do Android Studio

· No menu superior do Android Studio, selecione Tools > Device Manager.

· Se já existir um dispositivo virtual Android adequado, selecione o respetivo botão de início. Caso contrário, selecione Create Device ou o botão de adição, escolha um perfil de telemóvel, selecione uma imagem de sistema disponível, transfira-a se lhe for pedido e conclua o assistente. Inicie o novo dispositivo.

· De volta à barra de ferramentas superior do Android Studio, selecione esse dispositivo em execução no menu pendente de dispositivos. Mantenha app selecionado como configuração de execução e, em seguida, selecione o botão verde Run.

· Aguarde que a aplicação abra no emulador. Deverá ver Work instructions, Work order ID, Sandbox access token e Load work order.

Passo 4.2 Solicite o registo empresarial

· Na aplicação em execução no emulador, selecione Work order ID e introduza o número da ordem de teste do Passo 1.

· Na mesma aplicação, selecione Sandbox access token e cole o token temporário fornecido pela equipa de TI. Cole apenas o respetivo valor, sem a palavra Bearer.

· Selecione Load work order. Quando o pedido é bem-sucedido, a aplicação apresenta Read-only instructions loaded, seguido do número da ordem, do nome do equipamento, da revisão do procedimento e da primeira instrução.

· Selecione Next para ler a instrução seguinte. Selecione Previous para recuar. Desloque o conteúdo dentro da aplicação se uma instrução se estender para lá do fundo da janela.

Resultado esperado: o registo apresentado corresponde ao registo que abriu na aplicação empresarial no Passo 1. Se não carregar, consulte a secção de resolução de problemas antes de passar para o Aura.

Passo 5 Execute a mesma aplicação ligada no XREAL Aura

Passo 5.1 Prepare o Aura para desenvolvimento

· Ligue o Aura através do respetivo compute puck. Na aplicação Settings do Aura, ligue-se a uma rede Wi-Fi que consiga aceder à API do Passo 1. Peça à equipa de TI que confirme eventuais requisitos de rede privada.

· Siga as instruções atuais de integração para programadores fornecidas pela XREAL para ativar a depuração e ligar o compute puck ao computador. Comece pelas FAQ do Aura da XREAL (tutorials.xreal.com/docs/aura/troubleshooting/faq/), que incluem a entrada sobre recursos para programadores; comece por aí se precisar das instruções atuais.

· Na aplicação Settings do Aura, abra Developer options e ative o método de depuração suportado pelo seu dispositivo, seguindo essas instruções de integração. Autorize o seu computador de desenvolvimento se o Aura apresentar um pedido. O guia de dispositivos de hardware da Google explica o processo geral do Android. [7]

As designações exatas dos menus do Aura e a disposição dos cabos dependem do hardware e do firmware. As FAQ do XREAL Aura indicam que ambas as portas USB-C do compute puck suportam a depuração ADB padrão com o Android Studio, pelo que deve ligar o computador à Charging Port, à esquerda, e manter os óculos ligados à Glasses Port, à direita. A tabela de especificações indica suporte ADB completo apenas na Glasses Port, por isso experimente essa porta se a da esquerda não for reconhecida e utilize as instruções atuais da XREAL para ativar o acesso de programador. [1]

Passo 5.2 Instale a aplicação a partir do Android Studio

· No seu computador, regresse ao projeto AuraWorkOrders no Android Studio.

· Abra o menu pendente de dispositivos na barra de ferramentas superior do Android Studio. Selecione o seu dispositivo de desenvolvimento Aura ligado, em vez do emulador.

· Se o dispositivo não aparecer, selecione Tools > Troubleshoot Device Connections no Android Studio e siga o assistente de ligação. Confirme a autorização de depuração e o método de ligação nas instruções de integração da XREAL.

· Quando o dispositivo aparecer, mantenha app selecionado como configuração de execução e selecione o botão verde Run. O Android Studio compila, instala e inicia a aplicação no dispositivo selecionado.

Passo 5.3 Obtenha o registo nos óculos

· Coloque o Aura e encontre a janela da aplicação Work instructions que o Android Studio iniciou.

· Nessa janela, introduza o mesmo número de ordem de teste e o token temporário utilizados no Passo 4. Utilize os métodos de introdução disponíveis no seu dispositivo; os teclados e ratos Bluetooth padrão funcionam com o Aura (Settings > Connected Devices > Pair new device), e um teclado Bluetooth compatível pode simplificar a introdução de dados de teste. [1]

· Selecione Load work order e, em seguida, utilize Next, Previous e o deslocamento para ler as respetivas instruções.

· Compare o número da ordem, o nome do equipamento e o texto das instruções com o registo original na sua aplicação empresarial. Se corresponderem, demonstrou que a aplicação do Aura consegue obter e apresentar esse registo empresarial.

Problemas comuns e o que verificar

· A aplicação não é compilada: no Android Studio, abra View > Tool Windows > Build e leia o primeiro erro comunicado. Verifique o nome do pacote e se o projeto Empty Activity utiliza Compose e Material 3.

· A aplicação não consegue carregar a ordem: em MainActivity.kt, no Android Studio, confirme que o nome de anfitrião de exemplo foi substituído. Peça à equipa de TI que verifique se o endpoint está acessível a partir do emulador ou da rede do Aura.

· A API devolve 401: a API não aceitou a credencial. Peça à equipa de TI que verifique a validade do token e o serviço a que se destina, ou obtenha um novo token de teste.

· A API devolve 403: a conta não tem permissão. Peça ao administrador do sistema empresarial que conceda o acesso correto.

· A API devolve 404: verifique o número da ordem e se o endpoint aponta para o ambiente de teste correto.

· A API devolve dados, mas a aplicação falha: peça ao programador da API que compare a resposta com a Referência para programadores. O exemplo exige uma lista steps não vazia e um id que corresponda à ordem solicitada.

· Funciona no emulador, mas não no Aura: confirme a rota de rede e o acesso à API do Aura e, depois, verifique a aplicação no dispositivo. Não desative as verificações de certificados HTTPS para contornar um erro de ligação.

O exemplo mostra uma mensagem de falha genérica ao utilizador. Para obter o estado exato da API, peça ao administrador que inspecione os registos do servidor sem expor tokens nem ordens de trabalho completas. Para erros da aplicação, utilize View > Tool Windows > Logcat no Android Studio; o Logcat apresenta os registos da aplicação.

Referência para programadores da API de exemplo

Utilize esta secção ao verificar a resposta no Passo 1 ou ao adaptar fetchOrder no Passo 3. Descreve o contrato desta aplicação de exemplo, e não um endpoint fornecido pela XREAL.

Pedido: GET https://api.your-company.example/work-orders/WO-1001

Cabeçalhos do pedido: Authorization: Bearer <token de acesso de curta duração> e Accept: application/json

Resposta bem-sucedida esperada: HTTP 200 com esta estrutura JSON

{
  "id": "WO-1001",
  "asset": "Training station A",
  "revision": "3",
  "steps": [
    {
  	"number": 1,
  	"title": "Confirm the training station",
  	"instruction": "Match the station label to this work order. Stop if the labels differ.",
  	"expectedResult": "The station label matches Training station A."
    },
    {
  	"number": 2,
  	"title": "Review the reference label",
  	"instruction": "Read the sample label and compare it with the training reference sheet.",
  	"expectedResult": "The sample label matches the approved reference."
    }
  ]
}

O id identifica a ordem de trabalho, asset identifica o respetivo equipamento e revision identifica a versão do procedimento. Cada entrada dentro de steps tem um número, um título, uma instrução completa e um expectedResult. O exemplo ordena os passos por número.

Utilize instruções aprovadas para trabalho real; o exemplo descreve uma estação de formação inativa. Antes de passar à produção, valide o tamanho da resposta e o comprimento dos campos, rejeite dados de procedimento inválidos e defina o comportamento quando o token expira. A API tem de verificar a permissão para cada ordem solicitada. O código de exemplo é ilustrativo e não foi compilado nem testado num sistema real nem num dispositivo Aura físico.

Conclusão

Ligar o XREAL Aura a um sistema empresarial começa com um endereço de API aprovado e uma permissão de acesso, seguidos de uma aplicação do Android Studio que obtém o registo necessário. Testar a ligação num computador antes de a implementar no Aura ajuda a distinguir problemas de acesso aos dados de problemas de configuração do dispositivo. O exemplo da ordem de trabalho leva os detalhes do equipamento e as instruções passo a passo para um ecrã legível nos óculos, dando às empresas um ponto de partida prático para tornar a informação operacional acessível no local de trabalho. O início de sessão empresarial, as permissões adequadas e os testes no dispositivo preparam essa ligação para um piloto com colaboradores.

Fale sobre a disponibilidade do hardware e os requisitos do seu piloto com a VR Expert.

João Noronha

Escrito por

João Noronha

Especialista em XR e Conteúdo Imersivo na VR Expert

João Noronha é Especialista em XR e Conteúdo Imersivo na VR Expert, com um forte interesse por tecnologias emergentes e as suas aplicações práticas no mundo real. Dedica-se a transformar desenvolvimentos complexos em VR, AR, óculos de IA e tecnologia imersiva em conteúdos claros e práticos para empresas e profissionais que exploram o setor XR.

Perguntas frequentes

Este artigo

Um sistema precisa de uma API acessível, de um método de autenticação aprovado e de permissão para obter os registos necessários. O software de planeamento de recursos empresariais coordena as operações da empresa, enquanto o software de gestão da manutenção organiza a assistência aos equipamentos. As respetivas API e estruturas de dados variam, pelo que cada integração tem de ser verificada em função do produto e da configuração específicos.

A Google suporta interfaces Android padrão nos painéis de sistema do Android XR. As aplicações Android 2D para telemóvel ou para ecrã grande funcionam por predefinição no Android XR, apresentadas como um painel 2D dentro de um espaço XR/3D. Teste o início de sessão, o acesso à rede, a apresentação e a introdução de dados da aplicação no Aura antes de a aprovar para os colaboradores. Uma aplicação existente que já forneça os registos necessários pode reduzir a quantidade de desenvolvimento necessária. [4]

Uma janela de aplicação Android padrão consegue apresentar a ordem de trabalho e as respetivas instruções. Os painéis Jetpack XR personalizados são uma extensão opcional quando uma tarefa específica beneficia de uma disposição diferente da informação. [4]

Uma API interna da empresa pode estar acessível através de uma rede local ou privada aprovada. O dispositivo continua a ter de conseguir aceder à API e a quaisquer serviços necessários para a autenticação. O exemplo requer uma ligação ativa e não armazena ordens de trabalho para utilização offline.

O exemplo obtém e apresenta informações. Submeter resultados requer uma operação de API adicional, permissão do utilizador e uma interface de confirmação. O servidor tem de validar a submissão e tratar pedidos repetidos de forma segura.