Visão geral

O KlugGallery salva imagens e vídeos do seu app AIR na galeria de fotos do dispositivo: um BitmapData, como um snapshot, ou um arquivo de foto ou vídeo que o seu app gravou ou baixou.

Ele pede apenas o que é necessário para salvar. No iPhone e iPad, solicita acesso somente para adicionar, então o seu app nunca vê a biblioteca do usuário. No Android 10 e posteriores, salvar não exige nenhuma permissão; no Android 6 a 9, o KlugGallery pede acesso ao armazenamento em tempo de execução.

Os arquivos ficam onde os usuários os procuram: no Fotos no iOS, e em Pictures/<app name> ou Movies/<app name> no Android.

O KlugGallery é usado diariamente em nossos apps no iOS e Android, nossa prova de conceito.

Recursos

Autossuficiente: uma ANE, sem biblioteca principal nem ANEs de dependência para adicionar
Salvar um BitmapData como PNG ou JPEG, com qualidade e nome de arquivo
Copiar um arquivo de foto ou vídeo para a galeria (mp4, mov e m4v são salvos como vídeos)
iOS: acesso às fotos somente para adicionar, a biblioteca do usuário continua privada
Android 10 e posteriores: nenhuma permissão necessária; Android 6 a 9: permissão de armazenamento em tempo de execução
Pasta de álbum própria por app no Android
Status da permissão e um atalho para as configurações do app após uma recusa
Um evento por resultado, com a mensagem de erro quando algo falha

Plataformas compatíveis

iOS iPhone · iPad · Fotos, acesso somente para adicionar

Android celulares · tablets · dobráveis · MediaStore

Em outras plataformas, isSupported retorna false, de modo que o mesmo código pode permanecer em um app multiplataforma.

Primeiros passos

Adicione a extensão ao descritor do seu aplicativo:

app.xml

<extensions>
    <extensionID>com.klug.gallery</extensionID>
</extensions>

iOS: explique nas InfoAdditions por que o seu app salva no Fotos:

app.xml · iPhone InfoAdditions

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Saves your snapshots and videos to Photos.</string>

Android: necessário apenas para o Android 6 a 9; versões mais recentes o ignoram.

app.xml · Android manifest

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
                 android:maxSdkVersion="28"/>
<application>
    <activity android:name="com.klug.gallery.KlugGalleryPermissionActivity" android:exported="false"
              android:theme="@android:style/Theme.Translucent.NoTitleBar"/>
</application>

Exemplos de código

Três fluxos completos, extraídos da API que roda em nossos apps. Cada chamada retorna imediatamente; o resultado chega como um GalleryEvent. Documentação completa →

1 · Salvar um snapshot

Snapshot.as

import com.klug.gallery.Gallery;
import com.klug.gallery.GalleryEvent;
import flash.display.BitmapData;

var gallery:Gallery = Gallery.getInstance();
gallery.addEventListener( GalleryEvent.ADD_COMPLETE, function( e:GalleryEvent ):void {
    showToast( "Saved to your gallery" );   // your app function
});
gallery.addEventListener( GalleryEvent.ADD_ERROR, function( e:GalleryEvent ):void {
    trace( "could not save: " + e.status );   // the error message
});

function saveSnapshot( picture:BitmapData ):void
{
    if ( !gallery.isSupported ) return;
    // "png" or "jpg"; quality 0..1 counts for jpg
    gallery.addBitmapData( picture, "jpg", 0.9, "snapshot.jpg" );
}

2 · Salvar um vídeo gravado

Video.as

import flash.filesystem.File;

gallery.addEventListener( GalleryEvent.ADD_FILE_COMPLETE, function( e:GalleryEvent ):void {
    showToast( "Video saved" );
});
gallery.addEventListener( GalleryEvent.ADD_FILE_ERROR, function( e:GalleryEvent ):void {
    trace( "could not save the video: " + e.status );
});

// a File or a native path; mp4, mov and m4v are saved as videos, everything else as a photo
var clip:File = File.applicationStorageDirectory.resolvePath( "clips/last.mp4" );
gallery.addFile( clip );

3 · Pedir permissão somente quando necessário

Permission.as

var pending:BitmapData;

function save( picture:BitmapData ):void
{
    var status:String = gallery.authorisationStatus();
    if ( status == Gallery.AUTHORISED || status == Gallery.LIMITED )
        gallery.addBitmapData( picture, "png" );
    else if ( status == Gallery.DENIED || status == Gallery.RESTRICTED )
        askToOpenSettings();                 // your dialog, then gallery.openDeviceSettings()
    else
    {
        pending = picture;                   // not asked yet: show the system prompt
        gallery.requestAuthorisation();
    }
}

gallery.addEventListener( GalleryEvent.AUTHORISATION, function( e:GalleryEvent ):void {
    if ( e.status == Gallery.AUTHORISED && pending != null )
        gallery.addBitmapData( pending, "png" );
    pending = null;
});

Visão geral da API

Gallery.getInstance()	Retorna a instância única.
isSupported	Verdadeiro no iOS e Android, falso nas demais plataformas.
authorisationStatus()	AUTHORISED, DENIED, NOT_DETERMINED, SHOULD_EXPLAIN, RESTRICTED, LIMITED ou UNKNOWN.
requestAuthorisation()	Mostra o prompt do sistema enquanto o usuário ainda não decidiu. A resposta chega como GalleryEvent.AUTHORISATION.
addBitmapData(bitmapData, format, quality, filename)	Salva a imagem como "png" ou "jpg". Resultado: ADD_COMPLETE ou ADD_ERROR.
addFile(file)	Copia um arquivo de foto ou vídeo (File ou caminho nativo) para a galeria. Resultado: ADD_FILE_COMPLETE ou ADD_FILE_ERROR.
canOpenDeviceSettings	Verdadeiro onde as configurações do app podem ser abertas.
openDeviceSettings()	Abre a página de configurações do seu app.

Eventos

GalleryEvent: o type indica o que aconteceu, status traz os detalhes.

GalleryEvent.AUTHORISATION	status = o novo status da permissão
GalleryEvent.ADD_COMPLETE	a imagem foi salva
GalleryEvent.ADD_ERROR	status = a mensagem de erro
GalleryEvent.ADD_FILE_COMPLETE	o arquivo foi salvo
GalleryEvent.ADD_FILE_ERROR	status = a mensagem de erro

Compre o KlugGallery

Uma licença anual para um app AIR, com todas as atualizações por 12 meses. Após o pagamento, você recebe a extensão, a biblioteca ActionScript e a documentação por e-mail, normalmente em até um dia útil. Licença e termos

Simples

€19 / ano

Licença para um app AIR
Todas as atualizações por 12 meses
Sem suporte

Comprar Simples

Padrão

€149 / ano

Licença para um app AIR
Todas as atualizações por 12 meses
Resposta por e-mail em até 7 dias

Comprar Padrão

Prioritário

€299 / ano

Licença para um app AIR
Todas as atualizações por 12 meses
Resposta por e-mail em até 48 horas

Comprar Prioritário

Os impostos são calculados no checkout pelo Link (Stripe). Você informa o ID do aplicativo do seu app AIR durante o checkout.

Requisitos

AIR SDK	51.x (HARMAN)
iOS	iOS 13 ou posterior (acesso somente para adicionar a partir do iOS 14)
Android	Android 6.0 (API 23) ou posterior
Descritor iOS	NSPhotoLibraryAddUsageDescription nas InfoAdditions
Descritor Android	Activity de permissão; permissão de armazenamento para Android 6 a 9

KlugGallery

NÃO É NECESSÁRIO APM. Baixe e aproveite. Não tem como ser mais simples. Basta atualizar o Adobe AIR SDK. Se precisar de ajuda, estamos aqui.