Klientská sada SDK Cordovy

Tento modul plug-in poskytuje integraci na straně klienta pro službu CodePush, která umožňuje snadné přidání dynamického prostředí aktualizace do aplikací Cordovy.

Jak to funguje?

Aplikace Cordova se skládá ze souborů HTML, CSS a JavaScriptu a všech doprovodných obrázků, které jsou spojené rozhraním příkazového řádku Cordovy a distribuovány jako součást binárního souboru specifického pro platformu (tj. souboru .ipa nebo .apk). Jakmile se aplikace uvolní, aktualizace prostředků kódu nebo obrázku vyžaduje opětovné kompilaci a redistribuci celého binárního souboru. Tento proces zahrnuje čas kontroly pro úložiště, do kterých publikujete.

Modul plug-in CodePush pomáhá okamžitě získat vylepšení produktů před koncovými uživateli tím, že udržuje kód a obrázky synchronizované s aktualizacemi, které vydáte na server CodePush. Díky tomu vaše aplikace získá výhody offline mobilního prostředí a také "webovou" flexibilitu při načítání aktualizací bokem, jakmile budou k dispozici. Je to win-win!

Aby koncoví uživatelé měli vždy funkční verzi aplikace, modul plug-in CodePush udržuje kopii předchozí aktualizace, takže v případě náhodného nasdílení aktualizace, která zahrnuje chybové ukončení, se může automaticky vrátit zpět. Díky tomu můžete mít jistotu, že vaše nová flexibility vydané verze nebude mít zablokované uživatele, než budete mít možnost vrátit se zpět na server. Je to win-win-win!

Podporované platformy Cordova

Cordova 5.0.0+ je plně podporována spolu s následujícími přidruženými platformami:

• Android (cordova-android 4.0.0+) - včetně CrossWalk!
• iOS (cordova-ios 3.9.0+) – (Pokud chcete použít CodePush společně s cordova-plugin-wkwebview-engine modulem plug-in, musíte nainstalovat v1.5.1-beta+, který zahrnuje plnou podporu aplikací pomocí některého z webových zobrazení.)

Pokud chcete zkontrolovat verze jednotlivých platforem Cordovy, které aktuálně používáte, můžete spustit následující příkaz a zkontrolovat Installed platforms seznam:

    cordova platform ls

Pokud používáte starší platformu Androidu nebo iOS, než je uvedeno výše, a je otevřené pro upgrade, můžete to snadno provést spuštěním následujících příkazů (vynecháním platformy, pokud není potřeba):

    cordova platform update android
    cordova platform update ios

Začínáme

Jakmile budete postupovat podle pokynů "Začínáme" pro obecné účely pro nastavení účtu CodePush, můžete spustit CodePush-ifying aplikaci Cordova spuštěním následujícího příkazu v kořenovém adresáři vaší aplikace:

cordova plugin add cordova-plugin-code-push@latest

S nainstalovaným modulem plug-in CodePush nakonfigurujte aplikaci tak, aby ji používala pomocí následujících kroků:

1. Přidejte klíče nasazení do souboru config.xml a nezapomeňte přidat správný klíč pro každou platformu Cordova:

    <platform name="android">
        <preference name="CodePushDeploymentKey" value="YOUR-ANDROID-DEPLOYMENT-KEY" />
    </platform>
    <platform name="ios">
        <preference name="CodePushDeploymentKey" value="YOUR-IOS-DEPLOYMENT-KEY" />
    </platform>

Připomínáme, že tyto klíče se pro vás vygenerují při vytváření aplikace CodePush prostřednictvím rozhraní příkazového řádku. Pokud je potřebujete načíst, můžete spustit appcenter codepush deployment list -a <ownerName>/<appName> --displayKeysa získat klíč pro konkrétní nasazení, které chcete použít (např. Staging). Production

Od verze 1.10.0 můžete podepsat sady aktualizací (další informace o podepisování kódu najdete v příslušné části dokumentace). Pokud chcete povolit podepisování kódu pro aplikaci Cordova, měli byste nastavit veřejný klíč k ověření podpisu sady zadáním následujícího preference nastavení:config.xml

    <platform name="android">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>
    <platform name="ios">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>

Pro každou platformu můžete použít stejný pár privátních a veřejných klíčů.

1. Pokud v souboru config.xml používáte <access origin="*" /> prvek, aplikace už může komunikovat se servery CodePush a můžete tento krok bezpečně přeskočit. V opačném případě přidejte následující další <access /> prvky:

    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />

1. Pokud chcete zajistit, aby vaše aplikace přistupovala k serveru CodePush na platformách kompatibilních s CSP, přidejte https://codepush.appcenter.ms ji do značky Content-Security-Policy meta index.html v souboru:

    <meta http-equiv="Content-Security-Policy" content="default-src https://codepush.appcenter.ms 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *" />

1. Nakonec pečlivě zkontrolujte, jestli už máte cordova-plugin-whitelist nainstalovaný modul plug-in (většina aplikací bude). Pokud to chcete zkontrolovat, spusťte následující příkaz:

    cordova plugin ls    

Pokud cordova-plugin-whitelist je v seznamu, můžete jít. V opačném případě ho přidejte spuštěním následujícího příkazu:

    cordova plugin add cordova-plugin-whitelist

Teď jste připraveni použít modul plug-in v kódu aplikace. Další podrobnosti najdete v ukázkových aplikacích a dokumentaci k rozhraní API.

Využití modulů plug-in

S nainstalovaným a nakonfigurovaným modulem plug-in CodePush je jediné, co zbývá, přidat do aplikace potřebný kód pro řízení následujících zásad:

1. Kdy (a jak často) kontrolovat aktualizaci? (e.g. app spustit, v reakci na kliknutí na tlačítko na stránce nastavení pravidelně v určitém pevném intervalu)
2. Když je k dispozici aktualizace, jak ji prezentovat koncovému uživateli? Nejjednodušším způsobem, jak to udělat, je spustit následující příkaz v obslužné rutině deviceready události vaší aplikace:

codePush.sync();

Pokud je k dispozici aktualizace, stáhnou se tiše a nainstalují se při příštím restartování aplikace (buď explicitně koncovým uživatelem, nebo operačním systémem), což zajistí nejmenší invazní prostředí pro koncové uživatele. Pokud je dostupná aktualizace povinná, nainstaluje se okamžitě a zajistí, aby ji koncový uživatel získal co nejdříve.

Pokud chcete, aby vaše aplikace rychleji objevila aktualizace, můžete se také rozhodnout volat sync při každém obnovení aplikace z pozadí přidáním následujícího kódu (nebo něčeho ekvivalentního) v rámci chování vaší aplikace při spuštění. Můžete volat sync tak často, jak chcete, takže kdy a kde vám to zavolá, závisí na vašem osobním preferencích.

document.addEventListener("resume", function () {
    codePush.sync();
});

Pokud navíc chcete zobrazit potvrzovací dialog aktualizace (aktivní instalace), nakonfigurujte, kdy je nainstalovaná dostupná aktualizace (např. vynucení okamžitého restartování) nebo přizpůsobení prostředí aktualizace jakýmkoli způsobem, najdete sync v referenčních informacích k rozhraní API metody, kde najdete informace o tom, jak toto výchozí chování upravit.

Vydání aktualizací

Jakmile je vaše aplikace nakonfigurovaná a distribuovaná uživatelům a udělali jste nějaké změny kódu nebo prostředku, je čas je okamžitě uvolnit. Nejjednodušším (a doporučeným) způsobem, jak to udělat, je použít release-cordova příkaz v rozhraní příkazového řádku CodePush, který zpracovává přípravu a vydání aktualizace na server CodePush.

Ve své nejzásadnější podobě tento příkaz vyžaduje pouze jeden parametr: jméno vlastníka + "/" + název aplikace.

appcenter codepush release-cordova -a <ownerName>/<appName>
appcenter codepush release-cordova -a <ownerName>/MyApp-ios
appcenter codepush release-cordova -a <ownerName>/MyApp-android

Tento release-cordova příkaz umožňuje takový jednoduchý pracovní postup, protože rozumí standardnímu rozložení aplikace Cordova, a proto může vygenerovat aktualizaci a přesně vědět, které soubory se mají nahrát. Aby bylo možné podporovat flexibilní strategie vydávání verzí, release-cordova příkaz zveřejňuje řadu volitelných parametrů, které umožňují přizpůsobit způsob distribuce aktualizace koncovým uživatelům (např. které binární verze jsou s ní kompatibilní? Měla by se verze zobrazovat jako povinná?).

# Release a mandatory update with a changelog
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -m --description "Modified the header color"

# Release a dev Android build to 1/4 of your end users
appcenter codepush release-cordova -a <ownerName>/MyApp-android --rollout 25

# Release an update that targets users running any 1.1.* binary, as opposed to
# limiting the update to exact version name in the config.xml file
appcenter codepush release-cordova -a <ownerName>/MyApp-android --target-binary-version "~1.1.0"

# Release the update now but mark it as disabled
# so that no users can download it yet
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -x

Klient CodePush podporuje rozdílové aktualizace, takže i když vydáváte kód aplikace při každé aktualizaci, koncoví uživatelé budou stahovat jenom soubory, které potřebují. Služba to zpracovává automaticky, takže se můžete soustředit na vytváření skvělých aplikací a můžeme se starat o optimalizaci stahování koncových uživatelů.

Další podrobnosti o tom, jak release-cordova příkaz funguje, a také o různých parametrech, které zveřejňuje, najdete v dokumentaci k rozhraní příkazového řádku. Pokud byste také chtěli zpracovat spuštění cordova prepare příkazu sami, a proto chcete ještě flexibilnější řešení než release-cordova– další podrobnosti najdete v release příkazu.

Pokud narazíte na nějaké problémy nebo máte jakékoli dotazy, komentáře nebo zpětnou vazbu, můžete nám poslat e-mail nebo otevřít nový problém v tomto úložišti a my odpovíme ASAP! Přečtěte si také nápovědu a zpětnou vazbu.

Referenční dokumentace ke knihovně API

Rozhraní API CodePush se zpřístupní vaší aplikaci prostřednictvím globálního codePush objektu, který je k dispozici po deviceready spuštění události. Toto rozhraní API zveřejňuje následující metody nejvyšší úrovně:

• checkForUpdate: Zeptá se služby CodePush, zda má nakonfigurované nasazení aplikace k dispozici aktualizaci.
• getCurrentPackage: Načte metadata o aktuálně nainstalované aktualizaci (např. popis, čas instalace, velikost).
• getPendingPackage: Načte metadata pro aktualizaci (pokud existuje), která byla stažena a nainstalována, ale ještě nebyla použita prostřednictvím restartování.
• notifyApplicationReady: Oznámí modulu runtime CodePush, že je nainstalovaná aktualizace považována za úspěšnou. Pokud ručně kontrolujete a instalujete aktualizace (tj. nepoužíváte metodu synchronizace ke zpracování všech za vás), pak se tato metoda musí volat. Jinak CodePush bude považovat aktualizaci za neúspěšnou a při příštím restartování aplikace se vrátí k předchozí verzi.
• restartApplication: Okamžitě restartuje aplikaci. Pokud čeká na aktualizaci, zobrazí se koncovému uživateli okamžitě.
• synchronizace: Umožňuje vyhledat aktualizaci, stáhnout ji a nainstalovat, a to vše jedním voláním. Pokud nepotřebujete vlastní uživatelské rozhraní nebo chování, doporučujeme většině vývojářů tuto metodu použít při integraci CodePush do svých aplikací.

Kromě toho jsou následující objekty a výčty také zpřístupněny globálně jako součást rozhraní CodePush API:

• InstallMode: Definuje dostupné režimy instalace pro aktualizace.
• LocalPackage: Obsahuje informace o místně nainstalovaném balíčku.
• RemotePackage: Obsahuje informace o balíčku aktualizace, který je k dispozici ke stažení.
• SyncStatus: Definuje možné přechodné a výsledné stavy operace synchronizace .

codePush.checkForUpdate

codePush.checkForUpdate(onSuccess, onError?, deploymentKey?: String);

Dotazuje službu CodePush a zjistí, jestli má nakonfigurované nasazení aplikace k dispozici aktualizaci. Ve výchozím nastavení použije klíč nasazení nakonfigurovaný v souboru config.xml , ale můžete ho přepsat zadáním hodnoty prostřednictvím volitelného deploymentKey parametru. To může být užitečné, když chcete uživatele dynamicky přesměrovat na konkrétní nasazení, například povolit "přednostní přístup" přes velikonoční vejce nebo přepínač nastavení uživatele.

Po dokončení kontroly aktualizace aktivuje onUpdateCheck zpětné volání jednou ze dvou možných hodnot:

1. null pokud není k dispozici žádná aktualizace. K tomu dochází v následujících scénářích:
   • Nakonfigurované nasazení neobsahuje žádné verze, takže není potřeba nic aktualizovat.
   • Nejnovější vydaná verze v rámci nakonfigurovaného nasazení cílí na jinou binární verzi, než je aktuálně spuštěná (starší nebo novější).
   • Aktuálně spuštěná aplikace už má nejnovější verzi z nakonfigurovaného nasazení, takže tuto verzi už nepotřebuje.
2. Instance RemotePackage , která představuje dostupnou aktualizaci, kterou lze zkontrolovat a později stáhnout.

Parametry:

• onSuccess: Zpětné volání, které je vyvoláno při přijetí úspěšné odpovědi ze serveru. Zpětné volání obdrží jeden parametr, který je popsán výše.
• onError: Volitelné zpětné volání, které se vyvolá v případě chyby. Zpětné volání přebírá jeden parametr chyby, který obsahuje podrobnosti o chybě.
• deploymentKey: Volitelný klíč nasazení, který přepíše nastavení config.xml .

Příklad použití:

codePush.checkForUpdate(function (update) {
    if (!update) {
        console.log("The app is up to date.");
    } else {
        console.log("An update is available! Should we download it?");
    }
});

codePush.getCurrentPackage

codePush.getCurrentPackage(onSuccess, onError?);

Načte metadata o aktuálně nainstalovaném balíčku (např. popis, čas instalace). To může být užitečné pro scénáře, jako je zobrazení dialogového okna "co je nového?" po instalaci aktualizace nebo kontrola, jestli existuje čekající aktualizace, která čeká na použití prostřednictvím životopisu nebo restartování.

Po dokončení načítání aktualizace aktivuje onSuccess zpětné volání jednou ze dvou možných hodnot:

1. null pokud aplikace aktuálně spouští úvodní stránku HTML z binárního souboru, a ne z aktualizace CodePush. K tomu dochází v následujících scénářích:
   • Koncový uživatel nainstaloval binární soubor aplikace a ještě si nainstaloval aktualizaci CodePush.
   • Koncový uživatel nainstaloval aktualizaci binárního souboru (např. z úložiště), který vymazal staré aktualizace CodePush a dal přednost před binárním souborem.
2. Instance LocalPackage , která představuje metadata pro aktuálně spuštěnou aktualizaci CodePush.

Parametry:

• onSuccess: Zpětné volání, které je vyvoláno při přijetí metadat o aktuálně spuštěné aktualizaci. Zpětné volání obdrží jeden parametr, který je popsán výše.
• onError: Volitelné zpětné volání, které se vyvolá v případě chyby. Zpětné volání přebírá jeden parametr chyby, který obsahuje podrobnosti o chybě.

Příklad použití:

codePush.getCurrentPackage(function (update) {
    if (!update) {
        console.log("No updates have been installed");
        return;
    }

    // If the current app "session" represents the first time
    // this update has run, and it had a description provided
    // with it upon release, let's show it to the end user
    if (update.isFirstRun && update.description) {
        // Display a "what's new?" modal
    }
});

codePush.getPendingPackage

codePush.getPendingPackage(onSuccess, onError?);

Získá metadata pro aktuálně čekající aktualizaci (pokud existuje). Aktualizace se považuje za čekající, pokud je stažená a nainstalovaná, ale ještě nebyla použita prostřednictvím restartování aplikace. Aktualizace může být v tomto stavu pouze v případě, že InstallMode.ON_NEXT_RESTART byla zadána při volání sync nebo LocalPackage.installInstallMode.ON_NEXT_RESUME , a aplikace ještě nebyla restartována nebo obnovena (v uvedeném pořadí). Tato metoda může být užitečná, pokud chcete zjistit, jestli existuje čekající aktualizace, a pak uživatele vyzvat, aby ji okamžitě (prostřednictvím codePush.restartApplication) restartoval.

Po dokončení načítání aktualizace aktivuje onSuccess zpětné volání jednou ze dvou možných hodnot:

1. null pokud aplikace aktuálně nemá čekající aktualizaci (např. aplikace už používá nejnovější dostupnou verzi).
2. Instance LocalPackage , která představuje metadata pro aktuálně čekající aktualizaci CodePush.

Parametry:

• onSuccess: Zpětné volání, které je vyvoláno při přijetí metadat o aktuálně čekající aktualizaci. Zpětné volání obdrží jeden parametr, který je popsán výše.
• onError: Volitelné zpětné volání, které se vyvolá v případě chyby. Zpětné volání přebírá jeden parametr chyby, který obsahuje podrobnosti o chybě.

Příklad použití:

codePush.getPendingPackage(function (update) {
    if (update) {
        // An update is currently pending, ask the
        // user if they want to restart
    }
});

codePush.notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

Upozorní modul runtime CodePush, že by se měla považovat za úspěšnou čerstvě nainstalovanou aktualizaci, takže automatické vrácení na straně klienta není nutné. Je povinné volat tuto funkci někde v kódu aktualizované sady. V opačném případě se při příštím restartování aplikace modul runtime CodePush předpokládá, že nainstalovaná aktualizace selhala a vrátí se zpět k předchozí verzi. Toto chování vám pomůže zajistit, aby koncoví uživatelé nebyli blokováni poškozenou aktualizací.

Pokud používáte sync funkci a provádíte kontrolu aktualizace při spuštění aplikace, nemusíte volat notifyApplicationReady ručně, protože sync ji budete volat za vás. Toto chování existuje kvůli předpokladu, že při sync zavolání ve vaší aplikaci představuje dobrou aproximaci úspěšného spuštění.

Parametry:

• notifySucceeded: Volitelné zpětné volání vyvoláno, pokud byl modul plug-in úspěšně upozorněn.
• notifyFailed: Volitelné zpětné volání vyvoláno, pokud dojde k chybě s oznámením modulu plug-in.

codePush.restartApplication

codePush.restartApplication();

Okamžitě restartuje aplikaci. Tato metoda je určená pro pokročilé scénáře a je primárně užitečná, pokud jsou splněny následující podmínky:

1. Aplikace určuje hodnotu ON_NEXT_RESTART režimu instalace nebo ON_NEXT_RESUME při volání sync metod nebo LocalPackage.install metod. Tím se aktualizace neaktualizuje, dokud se aplikace nerestartuje (buď koncovým uživatelem, nebo operačním systémem), nebo se obnoví, takže se aktualizace okamžitě nezobrazí koncovému uživateli.
2. Máte událost uživatele specifickou pro aplikaci (např. koncový uživatel se vrátil zpět na domovskou trasu aplikace), která umožňuje aktualizaci použít nerušivým způsobem a potenciálně získá aktualizaci před koncovým uživatelem dříve, než čeká na další restartování nebo obnovení.

codePush.sync

codePush.sync(syncCallback?, syncOptions?, downloadProgress?, syncErrback?);

Synchronizuje kód a image vaší aplikace s nejnovější verzí s nakonfigurovaným nasazením. checkForUpdate Na rozdíl od metody, která kontroluje přítomnost aktualizace a umožňuje řídit, co dělat dál, sync zpracovává kontrolu aktualizací, stahování a instalace prostředí za vás.

Tato metoda poskytuje podporu pro dva různé (ale přizpůsobitelné) režimy, které umožňují snadné povolení aplikací s různými požadavky:

1. Bezobslužný režim (výchozí chování), který automaticky stáhne dostupné aktualizace a použije je při příštím restartování aplikace (např. operační systém nebo koncový uživatel ho zabil nebo se zařízení restartovalo). Tímto způsobem je celé prostředí aktualizace pro koncového uživatele "tiché", protože se nezobrazí žádná výzva k aktualizaci ani "syntetické" restartování aplikace.
2. Aktivní režim, který při dostupnosti aktualizace vyzve koncového uživatele k zadání oprávnění před jeho stažením a okamžitě tuto aktualizaci použije. Pokud byla aktualizace vydána pomocí povinného příznaku, koncový uživatel by stále dostával oznámení o aktualizaci, ale neměl by možnost ji ignorovat.

Příklad použití:

// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();

// Active update that lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync(null, { updateDialog: true, installMode: InstallMode.IMMEDIATE });

I když se metoda synchronizace pokusí snadno provádět tiché a aktivní aktualizace s malou konfigurací, přijímá následující volitelné parametry, které umožňují přizpůsobit mnoho aspektů výchozího chování uvedeného výše:

• syncCallback: Volá se, když se proces synchronizace přesune z jedné fáze do druhé v celkovém procesu aktualizace. Metoda je volána se stavovým kódem, který představuje aktuální stav a může být libovolnou SyncStatus z hodnot.
• syncOptions: Volitelný SyncOptions parametr, který konfiguruje chování operace synchronizace.
• downloadProgress: Volá se pravidelně při stahování dostupné aktualizace ze serveru CodePush. Metoda je volána s objektem DownloadProgress , který obsahuje následující dvě vlastnosti:
  • totalBytes (Number) – celkový počet bajtů očekávaných pro tuto aktualizaci (tj. velikost sady souborů, které se změnily z předchozí verze).
  • receivedBytes (Number) – počet bajtů stažených doposud, které lze použít ke sledování průběhu stahování.
• syncErrback: Volá se, když dojde k chybě v některém z interních kroků synchronizace. Metoda je volána se standardním javascriptovým Error objektem jako prvním argumentem.

SyncOptions

I když se sync metoda snaží snadno provádět tiché a aktivní aktualizace s malou konfigurací, přijímá objekt "options", který umožňuje přizpůsobit mnoho aspektů výchozího chování uvedené výše:

• deploymentKey (String) – Určuje klíč nasazení, který chcete dotazovat na aktualizaci. Ve výchozím nastavení je tato hodnota odvozena ze souboru config.xml , ale tato možnost umožňuje přepsat ji ze strany skriptu, pokud potřebujete dynamicky použít jiné nasazení pro konkrétní volání sync.
• installMode (InstallMode) – Určuje, kdy chcete nainstalovat volitelné aktualizace (tj. ty, které nejsou označené jako povinné). Výchozí hodnota InstallMode.ON_NEXT_RESTARTje . InstallMode Popis dostupných možností a jejich provedení najdete v referenčních informacích k výčtu.
• mandatoryInstallMode (InstallMode) – Určuje, kdy chcete nainstalovat aktualizace označené jako povinné. Výchozí hodnota InstallMode.IMMEDIATEje . InstallMode Popis dostupných možností a jejich provedení najdete v referenčních informacích k výčtu.
• minimumBackgroundDuration (Number) – Určuje minimální počet sekund, po který má aplikace být na pozadí před restartováním aplikace. Tato vlastnost se vztahuje pouze na aktualizace, které jsou nainstalovány pomocí InstallMode.ON_NEXT_RESUME, a může být užitečné pro získání aktualizace před koncovými uživateli dříve, aniž by to bylo příliš rušivé. Ve výchozím nastavení se 0použije aktualizace hned po obnovení, ale dlouho byla na pozadí.
• ignoreFailedUpdates (Boolean) – Určuje, jestli by měla být dostupná aktualizace ignorována, pokud byla dříve nainstalována a vrácena zpět do klienta (protože notifyApplicationReady nebyla úspěšně volána). Výchozí hodnota trueje .
• updateDialog (UpdateDialogOptions) – objekt "options" sloužící k určení, jestli se má koncovému uživateli zobrazit potvrzovací dialogové okno, když je k dispozici aktualizace, a pokud ano, jaké řetězce se mají použít. Výchozí hodnota nullje , která zakáže dialogové okno. Nastavením na libovolnou true hodnotu povolíte dialogové okno s výchozími řetězci a předáním objektu tomuto parametru povolíte dialogové okno a přepíšete jeden nebo více výchozích řetězců.

Následující seznam představuje dostupné možnosti a jejich výchozí hodnoty:

• appendReleaseDescription (Boolean) – označuje, jestli chcete k oznámení zobrazené koncovému uživateli připojit popis dostupné verze. Výchozí hodnota falseje .
• descriptionPrefix (String) – označuje řetězec, se kterým chcete přidat před popis verze, pokud existuje, při zobrazení oznámení o aktualizaci koncovému uživateli. Výchozí hodnota " Description: "je .
• mandatoryContinueButtonLabel (String):: Text, který se má použít pro tlačítko, musí koncový uživatel stisknout, aby nainstaloval povinnou aktualizaci. Výchozí hodnota "Continue"je .
• mandatoryUpdateMessage (String) – text použitý jako text oznámení o aktualizaci, pokud je aktualizace určena jako povinná. Výchozí hodnota "An update is available that must be installed."je .
• optionalIgnoreButtonLabel (String) – text, který se má použít pro tlačítko, může koncový uživatel stisknout a ignorovat volitelnou dostupnou aktualizaci. Výchozí hodnota "Ignore"je .
• optionalInstallButtonLabel (String) – text, který se má použít pro tlačítko, může koncový uživatel stisknout a nainstalovat volitelnou aktualizaci. Výchozí hodnota "Install"je .
• optionalUpdateMessage (String) – text použitý jako text oznámení o aktualizaci, pokud je aktualizace nepovinná. Výchozí hodnota "An update is available. Would you like to install it?"je . *- updateTitle (String) – text použitý jako záhlaví oznámení o aktualizaci, které se zobrazí koncovému uživateli. Výchozí hodnota "Update available"je .

Příklad použití:

// Download the update silently, but install it on
// the next resume, as long as at least 5 minutes
// has passed since the app was put into the background.
codePush.sync(null, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 60 * 5 });

// Download the update silently, and install optional updates
// on the next restart, but install mandatory updates on the next resume.
codePush.sync(null, { mandatoryInstallMode: InstallMode.ON_NEXT_RESUME });

// Changing the title displayed in the
// confirmation dialog of an "active" update
codePush.sync(null, { updateDialog: { title: "An update is available!" } });

// Displaying an update prompt that includes the
// description for the CodePush release
codePush.sync(null, {
   updateDialog: {
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
   },
   installMode: InstallMode.IMMEDIATE
});

// Silently check for the update, but
// display a custom downloading UI
// via the SyncStatus and DownloadProgress callbacks
codePush.sync(syncStatus, null, downloadProgress);

function syncStatus(status) {
    switch (status) {
        case SyncStatus.DOWNLOADING_PACKAGE:
            // Show "downloading" modal
            break;
        case SyncStatus.INSTALLING_UPDATE:
            // Hide "downloading" modal
            break;
    }
}

function downloadProgress(downloadProgress) {
    if (downloadProgress) {
    	// Update "downloading" modal with current download %
        //console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes);
    }
}

Metodu sync lze volat kdekoli, kde chcete vyhledat aktualizaci. To může být v obslužné rutině deviceready události, click události tlačítka, v zpětném volání pravidelného časovače nebo cokoli jiného dává smysl pro vaše potřeby. Podobně jako tato checkForUpdate metoda spustí požadavek na síť, aby zkontroloval aktualizaci na pozadí, takže nebude mít vliv na odezvu vlákna uživatelského rozhraní nebo vlákna JavaScriptu.

Zabalení objektů

getCurrentPackage Metody checkForUpdate vyvolávají zpětná volání úspěchu, které při aktivaci poskytují přístup k objektům "package". Balíček představuje aktualizaci kódu a také všechna další metadata (např. popis, povinný?). Rozhraní API CodePush má rozdíl mezi následujícími typy balíčků:

1. LocalPackage: Představuje staženou aktualizaci, která už je spuštěná, nebo je nainstalovaná a čeká na restartování aplikace.
2. RemotePackage: Představuje dostupnou aktualizaci na serveru CodePush, která ještě nebyla stažena.

LocalPackage

Obsahuje podrobnosti o aktualizaci, která byla stažena místně nebo již nainstalována. Odkaz na instanci tohoto objektu můžete získat buď voláním codePush.getCurrentPackage metody, nebo jako hodnotu zadanou pro zpětné RemotePackage.download volání úspěchu metody.

Vlastnosti

• appVersion: Nativní verze aplikace, pro které je tato aktualizace balíčku určená. (Řetězec)
• deploymentKey: Klíč nasazení balíčku. (Řetězec)
• description: Popis aktualizace. Jedná se o stejnou hodnotu, kterou jste zadali v rozhraní příkazového řádku při vydání aktualizace. (Řetězec)
• Instalace se nezdařila: Označuje, zda byla tato aktualizace dříve nainstalována, ale byla vrácena zpět. Metoda sync bude automaticky ignorovat aktualizace, které dříve selhaly, takže je nutné se starat pouze o tuto vlastnost, pokud používáte checkForUpdate. (Logická hodnota)
• isFirstRun: Příznak označující, jestli je aktuální spuštění aplikace první po použití balíčku. (Logická hodnota)
• isMandatory: Označuje, zda je aktualizace považována za povinnou. Toto je hodnota, která byla zadána v rozhraní příkazového řádku při vydání aktualizace. (Logická hodnota)
• label: Interní popisek automaticky udělený aktualizaci serverem CodePush, například v5. Tato hodnota jednoznačně identifikuje aktualizaci v rámci jejího nasazení. (Řetězec)
• packageHash: Hodnota hash SHA aktualizace. (Řetězec)
• packageSize: Velikost kódu obsaženého v aktualizaci v bajtech. (Číslo)

Metody

• install(installSuccess, installError, installOptions): Nainstaluje tento balíček do aplikace. Chování instalace závisí na zadaném installOptions. Ve výchozím nastavení je balíček aktualizace bezobslužně nainstalován a aplikace se znovu načte s novým obsahem při příštím spuštění aplikace. Při prvním spuštění po aktualizaci aplikace počká na codePush.notifyApplicationReady() volání. Po provedení tohoto volání se operace instalace považuje za úspěšnou. Jinak se operace instalace označí jako neúspěšná a aplikace se při příštím spuštění vrátí k předchozí verzi.

InstallOptions

Rozhraní definující několik možností pro přizpůsobení chování operace instalace.

• installMode: Slouží k určení installMode použitého pro operaci instalace. Výchozí hodnota InstallMode.ON_NEXT_RESTARTje .
• mandatoryInstallMode: Slouží k určení InstallMode použité pro operaci instalace, pokud je balíček povinný. Výchozí hodnota InstallMode.IMMEDIATEje .
• minimumBackgroundDuration: Pokud je InstallMode.ON_NEXT_RESUMEinstallMode , slouží k určení doby, po kterou musí být aplikace na pozadí, než se aktualizace nainstaluje, když bude obnovena. Výchozí hodnota 0je .

Příklad použití:

// App version 1 (current version)

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onInstallSuccess = function () {
    console.log("Installation succeeded.");
};

var onPackageDownloaded = function (localPackage) {
    // Install regular updates after someone navigates away from the app for more than 2 minutes
    // Install mandatory updates after someone restarts the app
    localPackage.install(onInstallSuccess, onError, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 120, mandatoryInstallMode: InstallMode.ON_NEXT_RESTART });
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        // The hash of each previously reverted package is stored for later use.
        // This way, we avoid going into an infinite bad update/revert loop.
        if (!remotePackage.failedInstall) {
            console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
            remotePackage.download(onPackageDownloaded, onError);
        } else {
            console.log("The available update was attempted before and failed.");
        }
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

//------------------------------------------------
// App version 2 (updated version)
var app = {
    onDeviceReady: function () {
        // Calling this function is required during the first application run after an update.
        // If not called, the application will be reverted to the previous version.
        window.codePush.notifyApplicationReady();
        // ...
    }
}

Příklad ochrany před chybnou aktualizací najdete v dokumentaci notifyApplicationReady().

RemotePackage

Obsahuje podrobnosti o aktualizaci, která je k dispozici ke stažení ze serveru CodePush. Odkaz na instanci tohoto objektu získáte voláním codePush.checkForUpdate metody, když je k dispozici aktualizace. Pokud používáte synchronizační rozhraní API, nemusíte se starat o RemotePackagerozhraní API, protože se automaticky zpracuje proces stahování a instalace.

Vlastnosti

Dědí RemotePackage všechny stejné vlastnosti jako vlastnost LocalPackage, ale obsahuje jednu další:

• downloadUrl: Adresa URL, kde je balíček k dispozici ke stažení. Tato vlastnost je potřebná pouze pro pokročilé použití, protože download metoda automaticky zpracuje získávání aktualizací za vás. (Řetězec)

Metody

• abortDownload(abortSuccess; abortError): Přeruší aktuální relaci stahování(pokud existuje).
• download(downloadSuccess, downloadError, downloadProgress): Stáhne aktualizaci balíčku ze služby CodePush. Zpětné downloadSuccess volání se vyvolá pomocí argumentu LocalPackage , který představuje stažený balíček. downloadProgress Volitelný zpětné volání se během stahování vyvolá několikrát pomocí jednoho DownloadProgress parametru.

DownloadProgress

Definuje formát objektu DownloadProgress, který slouží k odesílání pravidelných oznámení o průběhu stahování aktualizace.

Vlastnosti

• totalBytes: Velikost balíčku aktualizace stahování v bajtech. (Číslo)
• receivedBytes: Počet bajtů, které jsou již staženy. (Číslo)

Příklad použití:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Výčty

Rozhraní CodePush API obsahuje následující "výčtové" objekty, které lze použít k přizpůsobení prostředí aktualizace a jsou k dispozici globálně mimo window objekt:

InstallMode

Tento výčet zadaný, pokud chcete, aby byla skutečně použita nainstalovaná aktualizace, a lze jej předat buď metodám sync , nebo LocalPackage.install metodám. Obsahuje následující hodnoty:

• IMMEDIATE: Aktualizace se na spuštěnou aplikaci použije okamžitě. Aplikace se okamžitě znovu načte s novým obsahem.
• ON_NEXT_RESTART: Označuje, že chcete nainstalovat aktualizaci, ale ne vynuceně restartovat aplikaci. Když se aplikace "přirozeně" restartuje (z důvodu ukončení operačního systému nebo koncového uživatele), aktualizace se bez problémů vyzvedne. Tato hodnota je vhodná při provádění tichých aktualizací, protože by pravděpodobně narušovala koncového uživatele, pokud by se aplikace náhle restartovala z nikam, protože by si neuvědomili, že byla aktualizace dokonce stažena. Toto je výchozí režim používaný pro obě sync metody i LocalPackage.install pro metody.

Příklad ochrany před chybnou aktualizací najdete v dokumentaci notifyApplicationReady().

RemotePackage

Obsahuje podrobnosti o aktualizaci, která je k dispozici ke stažení ze serveru CodePush. Odkaz na instanci tohoto objektu získáte voláním codePush.checkForUpdate metody, když je k dispozici aktualizace. Pokud používáte synchronizační rozhraní API, nemusíte se starat o RemotePackagerozhraní API, protože se automaticky zpracuje proces stahování a instalace.

Vlastnosti

Dědí RemotePackage všechny stejné vlastnosti jako vlastnost LocalPackage, ale obsahuje jednu další:

• downloadUrl: Adresa URL, kde je balíček k dispozici ke stažení. Tato vlastnost je potřebná pouze pro pokročilé použití, protože download metoda automaticky zpracuje získávání aktualizací za vás. (Řetězec)

Metody

• abortDownload(abortSuccess; abortError): Přeruší aktuální relaci stahování(pokud existuje).
• download(downloadSuccess, downloadError, downloadProgress): Stáhne aktualizaci balíčku ze služby CodePush. Zpětné downloadSuccess volání se vyvolá pomocí argumentu LocalPackage , který představuje stažený balíček. downloadProgress Volitelný zpětné volání se během stahování vyvolá několikrát pomocí jednoho DownloadProgress parametru.

DownloadProgress

Definuje formát objektu DownloadProgress, který slouží k odesílání pravidelných oznámení o průběhu stahování aktualizace.

# Vlastnosti

• totalBytes: Velikost balíčku aktualizace stahování v bajtech. (Číslo)
• receivedBytes: Počet bajtů, které jsou již staženy. (Číslo)

Příklad použití:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Výčty

Rozhraní CodePush API obsahuje následující "výčtové" objekty, které lze použít k přizpůsobení prostředí aktualizace a jsou k dispozici globálně mimo window objekt:

InstallMode

Tento výčet zadaný, pokud chcete, aby byla skutečně použita nainstalovaná aktualizace, a lze jej předat buď metodám sync , nebo LocalPackage.install metodám. Obsahuje následující hodnoty:

• IMMEDIATE: Aktualizace se na spuštěnou aplikaci použije okamžitě. Aplikace se okamžitě znovu načte s novým obsahem.
• ON_NEXT_RESTART: Označuje, že chcete nainstalovat aktualizaci, ale ne vynuceně restartovat aplikaci. Když se aplikace "přirozeně" restartuje (z důvodu ukončení operačního systému nebo koncového uživatele), aktualizace se bez problémů vyzvedne. Tato hodnota je vhodná při provádění tichých aktualizací, protože by pravděpodobně narušovala koncového uživatele, pokud by se aplikace náhle restartovala z nikam, protože by si neuvědomili, že byla aktualizace dokonce stažena. Toto je výchozí režim používaný pro obě sync metody i LocalPackage.install pro metody.
• ON_NEXT_RESUME: Označuje, že chcete nainstalovat aktualizaci, ale nechcete aplikaci restartovat, dokud ji koncový uživatel příště neobnoví z pozadí. Tímto způsobem nenarušíte jejich aktuální relaci, ale aktualizaci před nimi můžete získat dříve, než budete muset počkat na další přirozený restart. Tato hodnota je vhodná pro bezobslužné instalace, které lze použít při obnovení neinvazivním způsobem.

SyncStatus

Definuje možné stavy operace synchronizace . Existují dvě kategorie stavů: zprostředkující a výsledek (konečný). Přechodné stavy představují stavy průběhu operace synchronizace a nejsou konečné. Stavy výsledků představují konečné stavy operace synchronizace. Každá operace synchronizace končí pouze jedním stavem výsledku, ale může mít nulové nebo více přechodných stavů.

• UP_TO_DATE: Aplikace je plně aktuální s nakonfigurovaným nasazením.
• UPDATE_INSTALLED: Byla nainstalována dostupná aktualizace a spustí se buď okamžitě po vrácení funkce zpětného volání, nebo při příštím obnovení nebo restartování aplikace v závislosti na zadaném InstallMode stavu SyncOptions.
• UPDATE_IGNORED: Aplikace má volitelnou aktualizaci, kterou koncový uživatel zvolil ignorovat. (To platí jenom v případě, že updateDialog se používá)
• CHYBA: Během operace došlo k sync chybě. Může se jednat o chybu při komunikaci se serverem, stažením nebo zrušením aktualizace. Protokoly konzoly by měly obsahovat další informace o tom, co se stalo. V tomto případě nebyla použita žádná aktualizace.
• IN_PROGRESS: Už je spuštěná jiná synchronizace, takže se tento pokus o synchronizaci přerušil.
• CHECKING_FOR_UPDATE: Server CodePush se dotazuje na aktualizaci.
• AWAITING_USER_ACTION: Je k dispozici aktualizace a koncovému uživateli se zobrazilo potvrzovací dialogové okno. (To platí jenom v případě, že updateDialog se používá)
• DOWNLOADING_PACKAGE: Z serveru CodePush se stahuje dostupná aktualizace.
• INSTALLING_UPDATE: Byla stažena dostupná aktualizace a chystá se ji nainstalovat.

PhoneGap Build

Tento modul plug-in je kompatibilní s buildem PhoneGap a podporuje vytváření buildů pro Android a iOS. Aby ale CodePush vypočítal hodnotu hash binárního obsahu v Androidu, musí build PhoneGap k sestavení aplikace použít Gradle, což není jeho výchozí chování (používá Ant). Pokud chcete tento problém vyřešit, přidejte do souboru config.xml projektu následující prvek jako podřízený <platform name="android"> prvek:

<preference name="android-build-tool" value="gradle" />

Ukázkové aplikace

Komunita Cordovy graciously vytvořila některé úžasné opensourcové aplikace, které mohou sloužit jako příklady pro vývojáře, kteří začínají. Následující seznam obsahuje aplikace OSS Cordova, které také používají CodePush, a lze je použít k zobrazení toho, jak službu používají ostatní:

• PGDay CodePush Demo – ukázková aplikace vytvořená Rangle.io pro PhoneGap Day Europe 2016.