Guia de customização comercial do Firefox OS

Visão geral

Requires Firefox OS 1.0.1

Desde a versão 1.0.1, o Firefox OS usa o mesmo mecanismo que o Firefox para customizações. Todos os recursos mencionados nesse artigo funcionam no Firefox 1.0.2, salvo indicação em contrário.

Nós criamos um exemplo completo de customização do Gaia como parte do repositório Gaia. Estude isso para aprender em primeira-mão o que pode ser feito com a customização em tempo de compilação. Isso também pode ser referenciado no artigo abaixo. Se você precisa criar sua própria imagem de produção, você deve criar um outro repositório, copiar o modelo de customização dentro dele e fazer suas próprias alterações. Compile sua distribuição de produção com o comando:

make production GAIA_DISTRIBUTION_DIR=./your-customization-directory-name.

Abaixo a estrutura do exemplo de customização:

  customize-sample
  ├── power
  │   ├── carrier_power_on.png
  │   └── carrier_power_off.png
  ├── ringtones
  │   ├── list.json
  │   └── ringer_dream_theme.ogg
  ├── wallpapers
  │   ├── customize.png
  │   └── list.json
  ├── browser.json
  ├── calendar.json
  ├── contacts.json
  ├── costcontrol.json
  ├── homescreens.json
  ├── network.json
  ├── sensors.json
  ├── settings.json
  ├── sms-blacklist.json
  ├── support.json
  ├── wapuaprof.json
  └── apps.list

Nós discutiremos todas as customizações opcionais nas seções seguintes, mas primeiramente vamos ver como aplicar uma customização no Gaia.

Etapas para aplicar uma customização

Para aplicar o exemplo de customização no Gaia:

1. Clone o código fonte do Gaia do https://github.com/mozilla-b2g/gaia.
2. Você pode copiar o diretório gaia/customization/ para um novo diretório ou fazer sua customização diretamente no diretório gaia/customization/. O caminho para esse diretório é referenciado nesse artigo como <DISTRIBUTION_PATH>, obviamente altere isso para o caminho do seu diretório.
3. Conecte o dispositivo Firefox OS ao seu computador via USB e verifique se ele é reconhecido pelo ADB.
4. Compile o Gaia, especificando o local da customização com a variável de ambiente GAIA_DISTRIBUTION_DIR como por exemplo:
   

   GAIA_DISTRIBUTION_DIR=<DISTRIBUTION_PATH> make production

5. Você deve agora ter o Gaia compilado no seu dispositivo Firefox OS com as customizações aplicadas.

Se você copiar o diretório de customização para gaia/distribution/, basta executar o comando make sem especificar a variável de ambiente:

make production

Customizações em tempo de compilação

Veremos agora as diferentes opções disponíveis no modelo.

power/

Customiza as animações (ou imagens estáticas) durante o procedimento de ligar e desligar o dispositivo. Os arquivos podem ser animações MP4 ou imagens estáticas PNG.

Nomes de arquivos válidos são:

• carrier_power_on.png
• carrier_power_on.mp4
• carrier_power_off.png
• carrier_power_off.mp4

ringtones/

Toques customizados são incluídos aqui. list.json devem conter os nomes de arquivos dos toques, como isso:

  {
    "ringer_classic_courier.opus": "",
    "ringer_dream_theme.ogg": "",
    "ringer_loud_windchimes.opus": "",
    "ringer_bitbounce.opus": ""
  }

Toques customizados são selecionados no aplicativo de configuração em Sound > Ringer. O toque padrão deve ser configurado em settings.json, usando DataURI, você pode usar o comando datauri disponível em node/npm, instale-o digitando npm install datauri -g e converta o arquivo para DataURI: datauri <FILE>

wallpapers/

Papeis de parede customizados (arquivos PNG) devem ser incluídos aqui e listados em list.json, que podem ser selecionados no aplicativo de configuração em Display > Wallpaper.

O papel de parede padrão deve ser selecionado em settings.json, usando a seguinte linha:

"wallpaper.image": "image location"

browser.json

Esse arquivo permite adicionar customizações no aplicativo Browser, como favoritos e motor de busca padrão. Veja a seção Favoritos do navegador e motor de busca para mais detalhes de como fazer.

calendar.json

Esse arquivo permite usar seu próprio calendário customizado no aplicativo Calendário do Firefox OS. Você precisará especificar suas credenciais Google Oauth credentials. Adicionalmente, é necessário o acesso à API CalDav: para gerar a chave requerida pela API, você precisa ir na página do Google criando sua ID de cliente e seguir as seguintes instruções:

1. Abra o console API.
2. Crie um projeto e habilite Calendar CalDav API em APIs & auth > APIs.
3. Clique em Credentials.
4. Clique em Create new client ID
5. Selecione Installed application na opção Application type e Other na opção Installed application type, enão pressione Create Client ID. Será fornecido um Client ID e Client secret.
6. Abra o arquivo calendar.json, altere o client_id e client_secret com Client ID e Client secret fornecidos no console do Google API console
7. Salve e feche o arquivo.

camera.json (Tamanhos das imagens nos aplicativos Camera e Galeria)

{
  "maxImagePixelSize": 6000000,
  "maxSnapshotPixelSize": 4000000,
  "requiredEXIFPreviewSize": {
    "width": 1200,
    "height": 1222
  }
}

maxImagePixelSize e maxSnapshotPixelSize são os tamanhos máximos em pixels permitidos para visualização de uma imagem na Galeria e na Camera. O padrão é 5 mega-pixels (5*2²⁰ pixels; 5mp).

Opcionalmentem, você pode definir variáveis para especificar o tamanho mínimo da visualização EXIF (Exchangeable Image File) que será apresentada na visualização de tela cheia incluindo a propriedade requiredEXIFPreviewSize. Se você não especificar essa propriedade a visualização EXIF somente será utilizada se for grande o suficiente para preencher a tela na largura e altura nas duas orientações (retrato ou paisagem).

contacts.json

Os contatos listados nesse arquivo serão incluídos no banco de dados do aplicativo Contatos assim que o Gaia for compilado.

A seguir um exemplo do arquivo contacts.json:

[
   {
     "name": ["John Doe"],
     "givenName": ["John"],
     "familyName": ["Doe"],
     "nickname": ["Johnny"],
     "category": ["Work", "Racing Team"],
     "email": [
       {
         "type": ["personal"],
         "value": "[email protected]",
         "pref": true
       },
       {
         "type": ["work"],
         "value": "[email protected]"
       }
     ],
     "adr": [
       {
         "type": ["personal"],
         "streetAddress": "123 Foopy St.",
         "locality": "San Francisco",
         "region": "Downtown",
         "postalCode": "94030",
         "countryName": "US"
       }
     ]
   },
   {
     "name": ["CarrierX"],
     "email": [
       {
         "type": ["work"],
         "value": "[email protected]"
       }
     ],
     "url": [
       {
         "type": ["work"],
         "value": "https://www.carrierx.com"
       }
     ]
   }
 ]

homescreens.json

homescreens.json define os aplicativos que ficam na dock e página inicial do Firefox OS e em que ordem. Por padrão o arquivo parece com:

{"homescreens": [
   [
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ]
 ]}

No exemplo aparecem quatro aplicativos na dock. Se for incluído outro array, o conjunto de aplicativos aparecem na página 1 da tela inicial, o próximo conjunto na página 2 e assim por diante.

{"homescreens": [
   [ // We're in the dock!
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ],
   [ // We're on Page 1 of the homescreen
     ["apps", "email"],
     ["apps", "settings"],
     ["apps", "clock"],
     ["apps", "calendar"]
   ],
   [ // We're on Page 2 of the homescreen
     ["external-apps", "customapp1"],
     ["external-apps", "customapp2"],
     ["external-apps", "customapp3"],
     ["external-apps", "customapp4"]
   ]
 ]}

O primeiro item de cada sub-array é a pasta dentro da qual o aplicativo aparece, o segundo item é o nome do diretório do aplicativo.

Collections

Collections (coleção) são grupos de aplicativos que têm seus próprios ícones que aparecem na tela inicial. Quando o ícone é tocado, uma nova tela aparece contendo os ícones dos aplicativos da coleção. Veja  diretório collections no código fonte para ver quais coleções estão disponíveis por padrão:

• funny: Aproveite os últimos aplicativos de diversão.
• games: Jogos online.
• local: O que está acontecendo a sua volta?
• music: Escute suas músicas favoritas.
• news: Mantenha-se atualizado com as fontes mundiais de notícias.
• shopping: Seguindo as tendências das compras.
• showbiz: Encontre aplicativos para entretenimento.
• social: Siga sua rede social em qualquer lugar.
• sports: Os melhores aplicativos sobre esportes.
• tv: Aplicativos relacionados à TV.

Em cada um desses diretórios você encontrará arquivos de ícones com resoluções diferentes, mais um arquivo de manifesto que define o metadado sobre a coleção como nome, papel e caminhos para os ícones.

No arquivo homescreens.json é possível definir quais coleções devem ser carregadas, quais páginas devem aparecer e em qual ordem. Por exemplo, se nós quisermos especificar que apareçam as coleções shopping, social, sports e tv, devemos escrever:

{"homescreens": [
   [
     ["apps/homescreen/collections", "social"],
     ["apps/homescreen/collections", "games"],
     ["apps/homescreen/collections", "music"],
     ["apps/homescreen/collections", "showbiz"]
   ], [
     ["apps", "communications", "dialer"],
     ["apps", "sms"],
     ["apps", "browser"],
     ["apps", "camera"]
   ]
 ]}

Cada posição no nível mais alto do arry refe-se à página da tela inicial. Aqui, as coleções devem aparecer na dock, e os aplicativos individuais aparecerão na página um da tela inicial.

O que contém nas coleções

Coleções são compostas por dois tipos de aplicativos.

Aplicativos locais são definidos em tempo de compilação por meio de arquivos de manifesto, armazenados em /apps/homescreen/collections/<collectionName>/manifest.collection. Os aplicativos locais contidos em cada coleção são definidos no arquivo manifesto. Por exemplo, o manifesto da coleção social (contém os aplicativos discador, sms, contatos e email)  The local apps contained within each collection are defined in the mainfest file. For example, the social collection (contains dialer, sms, contacts and email apps) parece com:

{
  "name": "Social",
  "role": "collection",
  "provider_id": "289", // adaptive search identifier
  "apps": [
    ["apps", "communications", "dialer"],
    ["apps", "sms"],
    ["apps", "communications", "contacts"],
    ["apps", "email"]
  ],
  "default_locale": "en-US",
  "icons": {
    "60": "/collections/social/icon.png",
    "90": "/collections/social/[email protected]",
    "120": "/collections/social/[email protected]"
  }
 }

Aplicativos remotos são fornecidos pela busca adaptativa em tempo de execução quando o dispositivo está online.

Como traduzir coleções

Traduções de coleções devem ser definidas nos arquivos de localização no aplicativo tela inicial, no diretório apps/homescreen/locales/. Cada arquivo de localização tem a seguinte estrutura de nome collections.<langCode>.properties — onde <langCode> é por exemplo fr para francês — e contém linhas simples contendo a string em inglês e sua versão traduzida. Um exemplo de arquivo de localização em francês:

# Add bookmark to homescreen
add-to-home-screen=Ajouter à l’écran d’accueil
add-to-home-screen-header=Ajouter un lien
website-name=Nom du site web
address=Adresse
added-to-home-screen=Ajouté à l’écran d’accueil

Coleções customizadas

Requires Firefox OS 1.3

Assim como no Firefox OS 1.3, você pode definir suas próprias coleções. Simplesmente crie-as no diretório collections, e faça a referência ao diretório no arquivo collections.json, como mostrado acima.

Propriedades da tela inicial vertical

A partir do Firefox 2.0, você pode escolher mostrar a tela inicial vertical ao invés do padrão na horizontal. As propriedades da tela inicial vertical são definidas em default-homescreens.json, incluindo quais aplicativos e coleções devem aparecer, quantas colunas a tela inicial deve ter e quais favoritos devem aparecer.

network.json (não na pasta de customização)

Requires Firefox OS 1.4 or below

Nas versões anteriores à Firefox OS esse arquivo pode ser criado em gaia/apps/settings/resources, e possibilita configurar os tipos de rede suportadas pelo dispositivo. Firefox OS suporta os seguintes tipos:

• 'wcdma/gsm' (preferência WCDMA)
• 'gsm'
• 'wcdma'
• 'wcdma/gsm-auto' (preferência GSM)
• 'cdma/evdo' (preferência CDMA)
• 'cdma'
• 'evdo'
• 'wcdma/gsm/cdma/evdo' (Automático)

A seguir um exemplo:

{
  "types":  [
    "cdma/evdo",
    "cdma", "evdo"
  ]
}

sensors.json

Define as capacidade do dispositivo com sensores. Por padrão contém:

{ "ambientLight": true }

Você pode configurar o valor para false caso deseje desabilitar o sensor.

settings.json

• Configurações gerais: Requires Firefox OS 1.0.1
• Provedor de busca do padrão do Rocketbar: Requires Firefox OS 2.0

Esse arquivo possibilita configurar os valores padrões da configuração como papel de parede, bloqueio de tela habilitado/desabilitado, bluetooth ligado/desligado, etc. Você pode consultar build/config/common-settings.json para verificar o que pode ser configurado em settings.json, por exemplo, você pode configurar "wifi.enabled": false para desabilitar o WiFi por padrão.

Você coloca suas configurações customizadas em customization/settings.json e então pode compilar usando make production GAIA_DISTRIBUTION_DIR=customization (ou outro diretório que você decida para fazer seu próprio prefil customizado).

No Firefox OS 2.0 e superiores, você pode definir as seguintes configurações adicionais no arquivo settings.json:

"search.urlTemplate": "https://www.google.com/search?q={searchTerms}",
"search.suggestionsUrlTemplate": "https://www.google.com/complete/search?client=firefox&q={searchTerms}",
"search.iconUrl": "data:image/x-icon;base64,AAABAAIAEBAAAAAAAAB9AQAAJ [TRUNCATED FOR BREVITY]

Customização do provedor de busca

Requires Firefox OS 2.0

No Firefox 2.0+, existe uma lista padrão de provedores de busca e seus arquivos de ícones em apps/settings/resources/search/providers.json. Você pode configurar isso em tempo de compilação modificando customization/search/providers.json e adicionando os arquivos de ícones apropriados no mesmo diretório. O conteúdo desse diretório irá sobrescrerver o diretório app/settings/resources/search se for encontrado no momento da compilação e se você copiar com o comando:

make production GAIA_DISTRIBUTION_DIR=customization.

Customizar o aplicativo Homescreen padrão

homescreen.appName possibilita especificar o aplicativo de tela de início padrão.

{ "homescreen.appName": "homescreen-stingray" }

sms-blacklist.json

Esse arquivo contem uma lista negra customizada de SMS: não é possível enviar SMS para os números especificados nessa lista. Ela sobrescreve a lista descrita no arquivo blacklist.json que fica no aplicativo SMS. Os números devem ser descritos em um array como o exemplo abaixo:

["11223344", "55667788"]

cellbroadcast

Canais de escuta:

• availability: runtime: Settings — ril.cellbroadcast.searchlist
• type: string
• valid format: \d(-\d)?(,\d(-\d))*

Desabilitar reporte de eventos:

• availability:
  • run time: Settings — ril.cellbroadcast.disabled
  • build time: Preference — ril.cellbroadcast.disabled
• type: boolean
• meaning: true to completely shutdown Cell Broadcast reporting.

support.json

Esse arquivo contém contatos de suporte incluindo suporte online e suporte telefônico. Quando incluído, esse arquivo sobrescreve o arquivo support.json no aplicativo Settings. Uma vez que a customização irá sobrescrever as configurações padrão, se você quiser manter as configurações padrão e adicionar alguns recursos extras, você deve copiar essas configurações dos aplicativos do dispositivo e adiconar suas próprias customizações neles.

Abaixo um exemplo de como o JSON deve parecer:

{
   "onlinesupport": {
     "href": "https://support.mozilla.org/",
     "title": "Mozilla Support"
   },
   "callsupport": [
     {
       "href": "tel:12345678",
       "title": "Call Support 1"
     },
     {
       "href": "tel:87654321",
       "title": "Call Support 2"
     }
   ]
 }

perfil user agent WAP (wapuaprof.json)

O perfil user agent WAP sobrescreve as informações do user agent quando envia pacotes WAP.

apps.list

Isso permite que você especifique quais aplicativos você deseja carregar em tempo de execução (similar ao variant.json, como explicado na seção Aplicativos abaixo.

apps/*
external-apps/*
outoftree_apps/*

Você pode especificar aplicativos individuais ao invés de todo o diretório:

apps/email
apps/settings

Outras opções de customização

Existem muitas outras customizações que podem ser feitas. Vamos vê-las agora.

Favoritos do navegador e motor de busca padrão

Favoritos: Requires Firefox OS 1.0.1

Motor de busca padrão: Requires Firefox OS 1.2

Motor de busca padrão para Rocketbar em providers.json: Requires Firefox OS 2.0

Podem ser customizados em tempo de compilação com diferentes variantes por cada país e rede em uma compilação. Os dados customizados são inseridos no aplicativo do navegador na primeira vez que é executado, baseado nos códigos MCC e MNC do SIM Card presente no dispositivo.

O exemplo abaixo (browser.json) mostra uma configuração para a operadora Vivo no Brasil (724006, onde 724 é o código do Brasil e 006 código da Vivo de acordo com a codificação MCC e MNC), com um fallback padrão (000000) no caso de não coincidir o SIM card ou o mesmo não estiver presente.

content = {
   '000000': {
     'bookmarks': [
       { 'title': 'Mozilla',
         'uri': 'https://mozilla.org',
         'iconUri':
           'data:image/png;base64,AAABAAIAEBAAAAEAIABo[truncated]'
       },
       { 'title': 'Firefox OS',
         'uri': 'https://mozilla.org/firefoxos',
         'iconUri':
           'data:image/png;base64,AAABAAIAEBAAAAEA[truncated]'
       }
     ],
     'searchEngines' : [
        {
          'title': 'Google',
          'uri': 'https://www.google.com/search?q={searchTerms}',
          'iconUri':
            'data:image/png;base64,AAABAAIAEBAAAAEAIABoBAA[truncated]'
        }
      ],
      'settings' : {
        'defaultSearchEngine': 'https://www.google.com/search?q={searchTerms}'
      }
   },
 
   '724006': {
     "bookmarks": [
       { "title": "Vivo Busca",
         "uri": "https://www.google.com.br/m/search",
         "iconUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAC[truncated]"
       },
       { "title": "Serviços e Downloads",
         "uri": "https://vds.vivo.com.br",
         "iconUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACA[truncated]"
       },
       {
         "title": "Site Vivo",
         "uri": "https://www.vivo.com.br/conteudosmartphone",
         "iconUri": "data:image/jpg;base64,/9j/4AAQSkZJRg[truncated]"
       }
     ],
     'searchEngines' : [
        {
          'title': 'Yahoo',
          'uri': 'https://search.yahoo.com/search?q={searchTerms}',
          'iconUri':
            'data:image/png;base64,AAABAAIAEBAAAAEAIABoBAA[truncated]'
        }
      ],
      'settings' : {
        'defaultSearchEngine': 'https://search.yahoo.com/search?q={searchTerms}'
      }
   }
 };

No exemplo, se um SIM Card da Vivo estiver presente na primeira vez que for executado, o usuário verá os favoritos da Vivo e o Yahoo como o motor de busca. Se estiver um outro SIM Card ou nenhum, você verá os favoritos da Mozilla e o Google como motor de busca padrão. Existem algumas partes importantes a serem observadas:

• A propriedade defaultSearchEngine deve conicidir com a propriedade uri do motor de busca especificado. Essa string atua como um modelo para {searchTerms} placeholder, o qual será substituíro com a pesquisa do usuário em tempo de execução. Outros valores como strings de busca devem ser adicionadas à pesquisa do usuarío no template da URL.
• O favicon das URLs mostrados são dados da URLs codificados em base64 dos dados da imagem (truncados para abreviar) ao invés de URLs de HTTP. Isto é recomendado para que os ícones apareçam na primeira vez que o navegador é executado, mesmo se o usuário não esteja conectado à Internet.
• Observe que diversas customizações podem ser aplicadas para diferentes países e diferentes redes numa mesma imagem, com diferentes códigos de 6 dígitos representando cada variante. O código de 6 dígitos é construído com o código MCC mais o código MNC, completados com zeros à direita para garantir que tenham o tamanho de 3 dígitos cada.
• Quanto popular os dados padrão o navegador primeiro verificará a exata coincidência com os códigos MCC e MNC, se não coincidir vai tentar MCC+000 e finalmente não havendo coincidência fará o fallback para 000+000.
• Ao atualizar entre versões do Gaia, novas customizações somente serão aplicadas se o tipo de customização é um novo recurso em uma nova versão do Gaia para a qual está se atualizando. Customizações anteriores não serão sobrescritas.

Customização única da variante para sobrescrever a lista de provedores e o provedor de busca do Rocketbar

Requires Firefox OS 2.0

1. O provedor de busca padrão do Rocketbar e a lista de provedores pode ser customizada por MCC/MNC — dados adicionados na primeira vez que um SIM card é inserido no telefone — especificando-o nos arquivos JSON em seu diretório de distribuição. Por exemplo:
   • A lista de provedores por MCC/MNC é especificada em mobizilla_search.json no nosso exemplo de customização.
   • O provedor padrão do Rocketbar é especificado em mobizilla_default_search.json no nosso exemplo de customização.
2. variant.json então define qual arquivo .json é utilizado para especificar as configurações para cada par MCC/MNC pair; veja as linhas 47–48 no nosso exemplo:

   "search": "mobizilla/mobizilla_search.json",
   "default_search": "mobizilla/mobizilla_default_search.json",

3. variant.json é colocado no diretório raiz da nossa distribuição.
4. Para aplicar a configuração da variante única você deve definir a variável GAIA_DISTRIBUTION_DIR como o caminho para o diretório da sua distribuição quando compilar o Gaia.

Configurações de dados e mensagens

As configurações são customizadas em tempo de execução.

Para aplicar configurações específicas, altere gaia/shared/resources/apn/apns_conf_local.xml, simplesmente adicionando ou editando os blocos:

 <apn carrier="Test Network"
      mcc="001"
      mnc="01"
      apn="internet"
      user="user"
      password="password"
      proxy="127.0.0.1"
      port="8080"
      mmsc="https://127.0.0.1"
      mmsproxy="127.0.0.1"
      mmsport="8080"
      authtype="0"
      type="default,supl,mms"
  />

Configurações de correio de voz e broadcasting

Para aplicar as configurações, altere gaia/shared/resources/apn/operator_variant.xml. Incluindo ou editando os atributos conforme necessário:

   <operator carrier="Test Network with Operator Variant Settings"
       mcc="001"
       mnc="01"
       cellBroadcastSearchList="0,1,2,3"
       voicemail="999999"
   />

Perfil user agent WAP

O perfil user agent WAP é outra aplicação que permite customização em tempo de execução. Ele sobrescreve as informação do user agent quando envia pacotes WAP, baseado no MCC/MNC O perfil que sobrescreve possui as partes url e tagname, mas nós somente suportamos url em nossa implementação atual.

O user agent WAP usa o mesmo estilo de codificação que o navegador, embora "000000" é usado como perfil padrão. Um exemplo a seguir:

   {
     "000000": {
       "url": "https://example.url/default.xml"
     },
     "123001": {
       "url": "https://example.url/custom123001.xml"
     }
   }

Nesse exemplo, a url do perfil padrão é https://example.url/default.xml, para mcc = 123 e mnc = 001, a url é https://example.url/custom123001.xml. Se existir outro ic card com mcc = 123 e mnc=100, a seria https://example.url/default.xml.

Se o 000000 for removido desse exemplo:

  {
     "123001": {
       "url": "https://example.url/custom123001.xml"
     }
   }

A url do perfil UA do ic card com mcc = 123, mnc = 001 é agora sobrescrito por https://example.url/custom123001.xml. Nenhum outro será sobrescrito.

Se nós tivermos o "000000" como antes, mas também "123001" com nenhuma url dentro:

   {
     "000000": {
       "url": "https://example.url/default.xml"
     },
     "123001": {}
   }

Todos os perfis UA agora são sobrescritos por https://example.url/default.xml

Aplicativos

As aplicações instaladas no Firefox OS podem ser customizadas em tempo de execução de diversas formas (veja também esse artigo). Porém a melhor forma é editando o arquivo de configuração variant.json que permite os aplicativos serem seletivamente instalados e colocados na posição desejada na tela inicial, dependendo da codificação MCC/MNC. As aplicações customizadas podem ser incluídas à lista de aplicações padrão.

A parte relevante do arquivo variant.json tipicamente parece com:

   {
     "apps": {
       "puzzle":
         {
           "manifestURL": "https://owd.tid.es/store/packages/fe8e4a866c518a42db9d2041568684c1.webapp"
         },
       "store":
         {
           "manifestURL": "https://owd.tid.es/store/manifest.webapp",
           "installOrigin": "https://www.openwebdevice.com"
         }
     },
     "operators": [
       {
         "id": "movistar-co",
         "mcc-mnc": [
           "214-01",
           "214-02"
         ],
         "apps": [
           {
             "id": "store",
             "screen": 0,
             "location": 2
           }
         ]
       },
       {
         "id": "movistar-mx",
         "mcc-mnc": [
           "215-23"
         ],
         "apps": [
           {
             "id": "store",
             "screen": 0,
             "location": 2
           },
           {
             "id": "puzzle"
           }
         ]
       }
     ]
   }

• O primeiro objeto do JSON é chamado apps, e define os aplicativos a serem copiados durante a compilação. O exemplo usa dois aplicativos, um hospedado (store) e outro empacotado (puzzle). Observer que enquanto os aplicativos empacotados somente pecisam do manifestURL, os hospedados também precisam do installOrigin para que possam ser baixados.
• O segundo objeto, chamado operators, é responsável pela configuração baseada no MCC/MNC. O objeto contém um array de objetos para cada par MCC/MNC. Esses objetos definem o id da operadora, uma lista MCC/MNC para a configuração e uma lista de objetos apps definindo quais aplicativos serão instalados em cada caso.
• Cada objeto apps requer uma propriedade id e tem dois argumentos opcionais para configurar a posição na tela de inívio:
  • A propriedade screen indica o número da tela.
  • A propriedade location indica a posição na tela.

Contatos de suporte, contatos padrão, papel de parede e toque do telefone

O mesmo arquivo variant.json — usado para configurar os aplicativos em tempo de execução dependendo do par MCC/MNC — também serve para configurar recursos específicos adicionando alguns atributos em cada operadora. Assim uma operadora pode ter as seguintes configurações:

   { apps: ...
     "operators": [
       {
         "id": "movistar-co",
           "mcc-mnc": [
             "214-01",
             "214-02"
           ],
         "apps": [
           {
             "id": "store",
             "screen": 0,
             "location": 2
           }
         ],
         "support_contacts": "resources/support_contacts_movistar.json",
         "default_contacts": "resources/contacts_movistar.json",
         "ringtone": {
           "path": "resources/Movistar_Mid_ABR_128kbps.ogg",
           "name": "Tono Movistar"
         },
         "wallpaper": "resources/customize.jpg"
       },
       ...
   }

Para cada operadora:

1. support_contacts especifica o caminho para um arquivo contendo os contatos a serem exibidos na tela de ajuda (Settings > Help), oferecendo a mesma funcionalidade que support.json. O formato do arquivo é:

      {
        "onlinesupport": {
          "title": "Mozilla Support",
          "href": "https://test.mozilla.org/support"
        },
        "callsupport1": {
          "title": "Call Support (Primary)",
          "href": "tel:14155550001"
        },
        "callsupport2": {
          "title": "Call Support (Secondary)",
          "href": "tel:14155550002"
        }
      }

2. default_contacts contém o caminho para um arquivo que contém contatos que serão pré-carregados no aplicativo Contatos, dependendo do par MCC/MNC presente em tempo de execução. O nome das seções são os pares MCC/MNC, e o conteúdo da seção deve ser um array de contatos seguindo o mesmo formato que contacts.json. Por examplo:

       {
           "123123":
           [
               {name: ["John Doe"]},
               // etc
           ],
       }
   

3. ringtone configura o toque padrão e contém dois atributos, ambos obrigatórios:
   • path: O caminho para o arquivo de audio.
   • name: O nome a ser mostrado quando o toque for mostrado no aplicativo de configurações.
4. wallpaper contém o caminho para o arquivo de imagem (PNG) que será configurado como o papel de parede padrão.

Compilando aplicativos pré-empacotados

Mais cedo, nós discutimos sobre o arquivo apps.list, e agora ele pode ser usado para incluir aplicativos em sua imagem. Esses aplicativos precisam ser compilados de uma certa maneira, então adicionado no diretório gaia/external-apps.

Para compilar aplicativos web pré-empacotados você pode utilizar o script gaia-preload-app, que compila um webapp pré-empacotado a partir de uma URL .webapp URL. Ele pode aceitar manifestos de aplicativos hospedados, ou mini-manifestos de aplicativos empacotados.

Para empacotar um único aplicativo web

Informe a URL .webapp que você deseja empacotar e execute o seguinte comando:

python preload.py https://<webapp url>

Isso irá gerar um diretório com o mesmo nome do aplicativo, por exemplo accuweather.

Processamento batch para empacotar vários aplicativos web

Você pode criar um arquivo chamado list, contendo todos os nomes de aplicativos e locais .webapp que você deseja empacotar em um processo batch. O formato desse arquivo é:

    myFirstApp,https://www.firstapp.com/manifest.webapp
    mySecondApp,https://www.secondapp.com/manifest.webapp
    etc.

Você precisa salvar esse arquivo list no mesmo diretório do script preload.py, e então executar o seguinte comando:

    $ python preload.py

O script preload.py irá fazer um parse da lista e fazer a conversão para você.

metadata.json para aplicativo web pré-empacotado

Todo aplicativo web pré-empacotado deve ter um arquivo metadata.json no seu diretório raiz. O Firefox Marketplace conta com esse arquivo metadata.json para a atualização automática. Esse arquivo é gerado automaticamente pelo script preload.py.

Para um aplicativo hospedado, as propriedades do arquivo metadata.json são:

• origin: O nome do domínio da URL do aplicativo.
• manifestURL: O local do manifesto para o aplicativo hospedado.
• installOrigin(hosted): O local do aplicativo instalado numa customização. Para customizações deve ser sempre https://marketplace.firefox.com.
• etag: isso é usado para verificar atualizações. O valor do etag é recuperado pelo header parse html quando o arquivo .webapp é baixado do servidor.
• "removable": false; Defina isso como true para fazer com que o aplicativo não possa ser removido da tela inicial.
• "type": "hosted"; Defina o type como hosted para permissões padrão para seu aplicativo. Tipos privileged e certified não são permitidos para aplicativos hospedados.

Para um aplicativo empacotado, as propriedades do arqvuivo metadata.json são:

• origin: A origem será app://<app name>, por exemplo: app://poppit.
• manifestURL: Deve ser o local do mini-manifeseto. Para customizações, o  manifestURL sempre será um mini-manifesto do marketplace.firefox.com.
• installOrigin(hosted): O local do aplicativo instalado de uma customização, sempre deve ser https://marketplace.firefox.com.
• etag: isso é usado para verificar atualizações. O valor do etag é recuperado pelo header parse html quando o arquivo .webapp é baixado do servidor.
• packageEtag: Esse é o etag do aplicativo empacotado, recuperado pelo header parse html quando o pacote é baixado do servidor na primeira vez que uma atualização é detectada.
• "removable": false; Defina isso como true para fazer com que o aplicativo não possa ser removido da tela inicial.
• "type": "privileged"; Defina o type para privileged para conseguir premissões extras, defina type como certified para conseguir o maior nível de permissionamento para os recursos de sistema do Firefox OS.

Formato do arquivo update.webapp

Aplicativos empacotados têm um arquivo chamado update.webapp, que é utilizado para atualizações automáticas. O formato é similar ao do arquivo manifest.webapp, mas você deve incluir alguns atributos:

• package_path é o caminho para o arquivo compactado (zip).
• size é o tamanho do pacote em bytes.

  {
    "name": "Game Pack",
    "icons": {"60": "/icon-60.png", "128": "/icon-128.png"},
    "version": "1.1.2",
    "package_path": "/application.zip",
    "developer": {"url": "https://abc.com", "name": "abc Inc."},
    "release_notes": "2nd release",
    "locales": {"es": {"launch_path": "/index-es.html", "description": "show me customization."}},
    "size": 5460141
  }

Formato do aplicativo pré-empacotado

AppCache.

Se o arquivo manifest.webapp do seu aplicativo tem um appcache_path incluído nele, o script preload.py irá trazer o arquivo AppCache indicado e preparar a busca de todos os recursos descritos no arquivo AppCache. O aplicativo pré-empacotado AppCache é um pouco diferente já que o Gecko reconhece um formato diferente, mas é gerado automaticamente pelo script preload.py.

A estrutura do arquivo é:

    <app name>
       ├── manifest.webapp
       └── cache
             ├── manifest.appcache
             └── <resources>

Perguntas Frequentes

A seguir uma lista de perguntas comuns sobre customizações comerciais.

O que pode ser customizado?

• Marca
  • Animações de inicialização e desligamento do dispositivo.
  • Nome da rede na tela bloqueada e na bandeja de utilitários.
  • Logos no procedimento de primeiro uso.
• Localização
  • Localizações instaladas (shared/locales)
  • Localização padrão (GAIA_DEFAULT_LOCALE)
  • Layout padrão do teclado (Vários teclados podem ser habilitados, não vinculados ao local)
• Aplicativos
  • Aplicativos de terceiros pré-instalados (Gerenciado por customize.py)
  • Localização dos aplicativos na tela de início (Gerenciado por customize.py)
  • Licença
  • Configuração do provedor do processo de pagamento no aplicativo
• Configurações
  • Brilho da tela padrão
  • Informação do dispositivo — Modelo (nome ou código)
  • Informação do dispositivo — Conteúdo ou link para informações legais
  • Ajuda — Link para suporte online
  • Ajuda — Número telefônico do suporte
  • Ajuda — Link para guia do usuário
  • APN
  • Limitação do tamanho da mensagem MMS
  • Modo de recuperação de mensagem MMS
• Mídias pré-carregadas
  • Papeis de parede
  • Música
  • Vídeos
  • Galeria
• Sons
  • Início e desligamento do dispositivo
  • Toques do celular
  • Som das mensagens
• Everything.me
  • Opção para habilitar ou desabilitar essa funcionalidade
  • Conjutno de categorias padrão e aplicativos
• Navegador
  • Favoritos padrão
  • Motor de busca padrão

Como e onde definir o layout customizado do grid de aplicativos?

Atualmente é definido em gaia/apps/homescreen/js/init.json. customize.py. Seja cuidadoso com o formato desse arquivo.

É possível definir se um aplicativo é removível da tela de início?

Não. Todos os aplicativos em /system/b2g são não removíveis, os que estão em /data são removíveis. Uma vez que todos os aplicativos pré-carregados vêm do diretório /system, nós precisamos movê-los para o diretório /data se quisermos que sejam removíveis.

Como adicionar um aplicativo empacotado ou hospedado na imagem?

Ambos devem ser incluídos em gaia/external-apps. customize.py vai permitir a entrada do URL do manifesto de um aplicativo hospedado ou empacotado, baixá-lo no local correto e criar o arquivo metadata.json. Isso funcionará como a "etapa de compilação".

Nós temos metadados diferentes para aplicativos empacotados e hospedados para que seja possível distinguí-los.

Veja compilando aplicativos pré-empacotados para mais detalhes.

Como preparar um aplicativo hospedado pré-carregado para o suporte inicial offline?

Você precisa fornecer todos os arquivos para o cache no diretório external-apps/MY_APP/cache, juntamente com o manifesto AppCache.

Novamente, veja compilando aplicativos pré-empacotados para mais detalhes.

Quais customizações do Marketplace são possíveis?

• No dispositivo
  • A customização do dispositivo em relação a pagamentos se limita a preencher uma whitelist de provedores de pagamento. Há um conjunto de preferências para isso, documentados em Pagamentos Web.
  • Por exemplo, os telefones Mozilla B2G são enviados com nossa implementação do provedor de pagamento numa whitelist que é acessível ao Marketplace e aplicativos de terceiros para compras a partir do aplicativo via navigator.mozPay. Encontre mais informações sobre provedores de pagamento em Provedores de pagamento via Web.
  • Se alguma empresa quiser implementar seu próprio processamento de pagamento e colocá-la na whitelist, está livre para isso. Porém, por enquanto, o Firefox Marketplace está configurado somente para habilitar compras através dos provedores de pagamento da Mozilla.
• No servidor
  • O aplicativo que comercializa produtos/serviços define o preço para o produto e o processador de pagamentos da Mozilla seleciona a moeda baseado na rede do usuário. Nada, como moeda, taxas ou impostos regionais ou L10N são controlados por configurações no dispositivo (ainda).
  • Categorias específicas no Firefox Marketplace para a empresa com o logo/nome da operadora na região.
  • Aplicativos em destaque / promoções no Firefox Market Place, especificados pela operadora.

Existem muitas outras considerações quando incluir uma região ou operadora. Veja Incluindo Regiões e Operadoras para mais detalhes.

Como fazer para empacotar e armazenar alterações nas customizações comerciais?

Armazene somente os arquivos alterados, atualmente estão em vários locais no sistema de arquivos. No B2G v2, estamos considerando isso num único local, similar aos diretórios de marcas que temos hoje no Gecko.

Como compilar o produto com uma configuração comercial específica?

Copie seus arquivos alterados em um checkout do Gaia. customize.py fornecerá uma interface para definir o que for relevante, criar arquivos apropriados em locais apropriados no checkout do Gaia, então compile o perfil desse Gaia.

Como customizar a animação da inicialização / desligamento?

• Essa animação usa o formato do Android bootanimation.zip/desc.txt.
• Isso nos faz criar uma sequência de animação multi-part na qual nós podemos especificar coisas como tamanho, framerate e número de vezes que cada parte da animação se repete.
• Existe também transições animada de arquivos PNG que preenche o espaço entre a sequência bootanimation.zip e a transição para a tela de bloqueio, que é executada pelo Gaia.
• O tamanho no disco da animação padrão é de 8.2MB (looping) + 3.6MB (transição do frame 18) = Total de 11.8MB.
• Atualmente, a animação de desligamento é uma animação customizada de css baseado num design específico em bug 809342.