O pacote permite inicializar um aplicativo baseado em React, integrado ao Zendesk App Framework (ZAF), e permite que você comece rapidamente a desenvolver aplicativos para o Zendesk Sell.
Observação: os documentos são baseados no Guia do desenvolvedor do Zendesk. Eles contêm apenas informações selecionadas e, esperançosamente, as mais necessárias em termos de criação de um aplicativo integrado ao Zendesk Sell. Se você tiver dificuldades com alguma coisa ou não houver informações suficientes aqui, visite a documentação real.
A seguinte estrutura de pastas e arquivos devem ser incluídos em um aplicativo para que ele seja instalado com êxito em um produto Zendesk:
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
A seguir estão breves descrições dos arquivos necessários:
Exemplo de manifesto do aplicativo HubSpot for Sell:
{
"name" : " Hubspot " ,
"author" : {
"name" : " Zendesk " ,
"email" : " [email protected] " ,
"url" : " https://www.zendesk.com "
},
"defaultLocale" : " en " ,
"private" : false ,
"singleInstall" : true ,
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
}
}
},
"version" : " 2.0.3 " ,
"frameworkVersion" : " 2.0 " ,
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
],
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}
} Você deve declarar onde deseja que seu aplicativo apareça em cada interface do produto com a propriedade location em manifest.json. Os locais são onde os iframes podem aparecer no produto. Você pode especificar um ou mais locais em um ou mais produtos Zendesk. Por padrão, seu aplicativo estará disponível no Zendesk Sell em todos os cartões de objeto (Lead, Contato, Negócio) no painel do lado direito.
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
},
"deal_card" : {
"url" : " assets/index.html "
}
}
}Para locais disponíveis, consulte API Sell Apps. Para saber mais sobre como definir a localização do aplicativo, visite a seção Definir a localização do aplicativo no guia do desenvolvedor.
Quando um aplicativo faz solicitações AJAX, as configurações da solicitação podem ser visualizadas no console do navegador. Algumas configurações podem conter informações confidenciais, como uma chave de API ou um token. Uma maneira recomendada de evitar esse comportamento é usar OAuth Authentication . A outra opção pode ser usar Secure Settings . Escolha a opção que melhor lhe convier.
Você pode usar o OAuth2 para autenticar todas as suas solicitações de API para serviços externos. OAuth fornece uma maneira segura para seu aplicativo acessar os dados da sua conta sem exigir que informações confidenciais, como nomes de usuário e senhas, sejam enviadas com as solicitações. Para usar a autenticação OAuth, você precisa registrar seu aplicativo em um serviço de terceiros para gerar credenciais OAuth para seu aplicativo. Você também precisa adicionar algumas funcionalidades ao seu aplicativo para implementar um fluxo de autorização OAuth.
Ao registrar um aplicativo, você verá uma tela mostrando as configurações do seu novo aplicativo, incluindo o nome do aplicativo, a descrição e outras informações do aplicativo que você deve preencher. Além disso, você também encontrará as configurações de autenticação para seu aplicativo, como ID do cliente, segredo do cliente, URL de redirecionamento, bem como os escopos usados pelo seu aplicativo. Você precisará desses itens ao iniciar uma conexão OAuth entre seu aplicativo e um serviço de terceiros.
Client ID – esse ID é exclusivo do seu aplicativo e é usado para iniciar o OAuth.Client secret – usado para estabelecer e atualizar a autenticação OAuth.Redirect URL – Os usuários serão redirecionados para este local após concederem acesso ao seu aplicativo. Use um dos seguintes URLs:Scope - Medida de segurança opcional. O escopo determina quais dados seu aplicativo tem permissão para acessar.OAuth URL – um usuário precisará desse URL para conectar seu aplicativo. A URL está sendo construída com base nas credenciais do cliente, URL de redirecionamento e configuração de escopos do seu aplicativo. Use o Client ID e o Client secret em seu aplicativo conforme descrito na seção a seguir.
Depois de registrar seu aplicativo, você deverá definir as configurações do OAuth no arquivo manifest.json . Atualize client_id e client_secret com o seu.
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}Você também precisa adicionar um parâmetro do tipo "oauth" à lista de parâmetros:
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]Para mais informações visite a documentação
No código do seu aplicativo, use o espaço reservado {{setting.access_token}} e uma propriedade secure: true para fazer uma solicitação OAuth.
var settings = {
url : 'https://www.example.com/api/user' ,
headers : { "Authorization" : "Bearer {{setting.access_token}}" } ,
secure : true ,
type : 'GET'
} ;
var client = ZAFClient . init ( ) ;
client . request ( settings ) . then ( ... ) ; Esta é uma API somente JSON. Você deve fornecer um cabeçalho Content-Type: application/json em solicitações PUT e POST. Você deve definir um cabeçalho Accept: application/json em todas as solicitações.
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; As configurações seguras são outra maneira de tornar as configurações inacessíveis aos agentes ao fazer solicitações AJAX. Os valores de configuração são inseridos apenas na solicitação de saída do lado do servidor na camada proxy. Consulte Usando configurações seguras para configurá-las.
Embora você possa usar qualquer CSS personalizado ou estrutura de front-end para a aparência do seu aplicativo, a Zendesk recomenda usar o Zendesk Garden. O Zendesk Garden foi projetado para ser uma base comum de estilos e componentes entre todos os produtos Zendesk. Para que seu aplicativo corresponda à aparência do Zendesk, o Zendesk Garden é usado no aplicativo como padrão.
Exemplo:
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}Para obter mais informações sobre as classes CSS e os componentes React no Zendesk Garden, consulte garden.zendesk.com.
O cliente ZAF permite que seu aplicativo no iframe se comunique com o produto Zendesk host. Você pode usar o cliente em seus aplicativos para escutar eventos, invocar ações e acessar propriedades em cada local. Consulte o guia da API do cliente ZAF.
Exemplo:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )O pacote @zendesk/sell-zaf-app-toolbox oferece vários métodos, ganchos e componentes úteis que ajudam você a criar aplicativos React integrados ao Zendesk Sell com mais rapidez e menos esforço. Eles usam o App Framework Client da Zendesk nos bastidores. Para saber mais visite o repositório.
Use sua interface de linha de comando para navegar até a pasta que contém o aplicativo que você deseja testar.
Instale dependências, se necessário:
npm installInicie seu aplicativo com o seguinte comando:
npm startAbra uma nova janela no seu terminal e inicie o servidor:
npm run server
Em um navegador, navegue até a página do produto onde você especificou o aplicativo para aparecer (por exemplo, cartão de negócio/lead/contato) e anexe ?zcli_apps=true ao URL. Exemplo:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
Na barra de endereços do seu navegador, clique no ícone de escudo à direita (Chrome) ou no ícone de cadeado à esquerda (Firefox) e concorde em carregar um script inseguro (Chrome) ou desativar a proteção (Firefox).
Nota: O Safari não tem opção para desativar a proteção.
Para limpar e corrigir automaticamente alguns erros, execute:
npm run lintPara formatar seu código:
npm run prettierCrie um pacote com fontes minificadas:
npm run build O comando cria um novo arquivo .zip em dist/tmp . Agora seu aplicativo está pronto para ser instalado como um aplicativo privado no seu Zendesk Sell!
Integrations e selecione a guia Apps .Upload private app .dist/tmp em seu projeto de aplicativo local.Se seu aplicativo usa OAuth ou configurações seguras, você pode continuar testando-o localmente após instalá-lo remotamente.
zcli.apps.config.jsonplan e paramters ). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
} Para encontrar o ID de instalação do aplicativo, faça login na sua instância do Zendesk Sell como administrador e abra a seguinte página no mesmo navegador, substituindo your_subdomain pelo seu:
https://seu_subdomínio.zendesk.com/api/sell/apps/installations.json (em produção)
Localize seu aplicativo instalado e anote seu valor id , não seu valor app_id .
