StargateJS hybridization library for HTML5 apps
StargateJsApps is an hybridization library for hosted apps built around ManifoldJS approach to hybrid application.
Hosted apps are hybrid application that have their files served remotely by a web server and that are described by a manifest (W3C specification)
ManifoldJS is Cordova plugin developed by Microsoft that inject all Cordova dependency after the page is loaded, decoupling the native platform implementation with the web app.
StargateJsApps take advantage of the manifest to store it's configuration, like features to enable or remote api information.
Technical Documentation Game Module
use stargate.js or stargate.min.js in dist/ folder
Install stargate bower package and save to dependencies (not dev dependencies):
$ bower install -S stargatejs-apps
Static You can call static methods independently from initialization of Stargate
Require opened stargate You can call this type of methods only after Stargate is initialized and open: when Stargate is inside hybrid app and it had already fulfilled the initialization promise.
Before initialize You should call this type of methods before initialization of Stargate: they usually set some callback or status needed inside initialization.
Return promise This type of methods return a promise that is fulfilled when operation is succeeded.
Use callbacks This type of methods use also or only callbacks for returning success or failure.
[Static] get hybrid container status: true when we're running inside the hybrid app
Internally it check if there is an url query parameter called "hybrid" with value 1, or if there is a cookie or a localStorage with the same name and value.
Return boolean
[Static] return current Stargate version
[Static] get initialization status: true when initialization is already called
Return boolean
[Static] get initialization status: true when initialization is done
Return boolean
[Before initialize] Set the callback to call when an analytic event need to be sent.
Please call this before Stargate.initialize, so it can track events logged on initialize too, like MFP.
[Before initialize] Set the callback to call when converion data from AppsFlyer are received. You may need to save the data you receive, becouse you'll only got that data the first time the app is run after installation.
Please call this before Stargate.initialize, so it can call you during initialize too.
[Use callbacks,Return promise] Initialization of Stargate, you have to pass a configuration object and a callback that will be called when initialization has been finished.
Return a promise fulfilled when initialization has been finished.
If initialize has already been called then it will log a warning and will just execute the callback and return a promise that will be immediately fulfilled.
If initialize is called when we are outside hybrid environment (see Stargate.isHybrid) then it will just execute the callback and return a promise that will be immediately fulfilled.
The callback is called with a boolean result indicating if we are inside hybrid environment or not (see Stargate.isHybrid). Also the promise is fullfilled with the same boolean result.
It's a javascript object with configurations.
| Option | Type | Description | Default |
|---|---|---|---|
| modules | Array of string | List of modules to initialize | ["mfp","iapbase","appsflyer","game"] |
| modules_conf | Object | Configuration of submodule | {} |
| Value | Description |
|---|---|
| iap | InApp purchase module |
| iaplight | InApp purchase module based on AlexDisler/cordova-plugin-inapppurchase |
| mfp | Mobile Fingerprint purchase module |
| appsflyer | AppsFlyer module |
| game | Offline game module |
| Option | Description | Default |
|---|---|---|
| iap | InApp purchase configuration object | undefined |
| iaplight | InApp purchase iaplight configuration object | undefined |
| mfp | Mobile Fingerprint configuration object | undefined |
| appsflyer | AppsFlyer configuration object | undefined |
| Option | Description | Default | Example |
|---|---|---|---|
| country | Country to use for mfp | undefined |
"it" |
There are two more variable needed for Mobile FingerPrint to work and these variable are retrieved from the manifest.json inside the app:
| Value | Description |
|---|---|
| namespace | namespace |
| label | label |
| Option | Description | Default | Example |
|---|---|---|---|
| autologin | (boolean) enable autologin with pony value | undefined |
"true" |
| fieldPony | field where to look for the pony value | "af_sub1" |
"af_sub2" |
| fieldReturnUrl | field where to look for the return url value | undefined |
"af_sub5" |
The AppsFlyer module permit to autologin an user coming from the Webapp, when you pass from the Webapp to AppsFlyer the token of the user in the field which value is in fieldPony.
It also permit to go to a specific url (for example the url of the content where the user choosed to install the app) after it's logged in. This is done with the fieldReturnUrl value passed to the autologin url (api.mfpSetUriTemplate value in manifest.json).
There are two more variable needed for AppsFlyer to work and these variable are retrieved from the manifest.json inside the app:
| Value | Description |
|---|---|
| appstore_appid | iOS App id |
| appsflyer_devkey | devkey got from appsflyer |
| Option | Description | Example |
|---|---|---|
| id | Product id as registred on store | "stargate.test.spec.subscription" |
| alias | Product alias | "Stargate Test Subscription" |
| type | Type of product; it can be: FREE_SUBSCRIPTION, PAID_SUBSCRIPTION, CONSUMABLE, NON_CONSUMABLE | "PAID_SUBSCRIPTION" |
| Option | Description | Example |
|---|---|---|
| productsIdAndroid | Array of Product id as registered on Google Store | ["stargate.test.spec.subscription1","stargate.test.spec.subscription2"] |
| productsIdIos | Array of Product id as registered on Apple Store | ["stargate.test.spec.ios.subscription1","stargate.test.specios..subscription2"] |
var configurations = {
modules: ["mfp", "appsflyer", "iaplight", "game"],
modules_conf: {
"iaplight": {
"productsIdAndroid": ["com.mycompany.myapp.weekly.v1","com.mycompany.myapp.montly.v1"],
"productsIdIos": ["com.mycompany.myapp.weekly.v1","com.mycompany.myapp.montly.v1"]
},
"mfp": {
"country": "us"
}
}
};
var callback = function(result) {
console.log("Stargate initialized with result: "+result);
};
// you can use the callback ...
Stargate.initialize(configurations, callback);
// ... or the promise interface
Stargate.initialize(configurations, function(){})
.then(function(result) {
console.log("Stargate initialized with result: "+result);
})
.fail(
function(error) {
console.error("Stargate initialization error: ", error);
});[Require opened stargate] Open external url with InApp Browser
var info = Stargate.checkConnection();
Stargate.checkConnection(function(info){ console.log(info.networkState, info.type); });
// info is equal to: {'networkState': "wifi|3g|4g|none", type:"online|offline"}[Require opened stargate,Use callbacks] The connection info object is updated to the last connection status change the networkState is retrieved from navigator.connection.type of cordova-plugin-network-information plugin
[Require opened stargate,Use callbacks] Call callbackSuccess with an object with the device id like this: {'deviceID': deviceID} deviceID got from uuid of device plugin
[Require opened stargate,Use callbacks] Show/hide device status bar
Parameter boolean visibility
[Require opened stargate,Use callbacks] Facebook connect
Parameter string scope: scope list separeted with comma
[Require opened stargate,Return promise] Share an url on a social network
| Options key | Description | Example |
|---|---|---|
| type | String: social network to use (chooser, facebook, twitter, whatsapp) | chooser |
| url | String: url to share | "http://www.google.com/?utm_source=stargate" |
Promise fullfilled when sharing is done
[Require opened stargate,Return promise] Return a list of social networks application installed on user device
| Options key | Description | Example |
|---|---|---|
| socials | Object with socials to check if available (facebook, twitter, whatsapp) | {"facebook": true, "twitter": true, "instagram": false } |
| url | String: url to share | "http://www.google.com/?utm_source=stargate" |
Promise fullfilled with an object with social networks availablility from the ones requested with parameter "option.socials" For example:
{
"facebook": true,
"twitter": true,
"instagram": false
}[Require opened stargate,Return promise] Return an object with In App Product information got from store on module initialization
iap product id by which information will be returned
Promise fullfilled with an object with iap product information:
- productId - SKU / product bundle id (such as 'com.yourapp.prod1')
- title - short localized title
- description - long localized description
- price - localized price
For example:
{
"productId": "com.mycompany.myproduct.weekly.v1",
"title": "Abbonamento Premium MioProdotto",
"description": "Abonamento premium al MioProdotto",
"price": "€0,99"
}[Require opened stargate,Return promise] Request subscription of In App Product on store
iap product id to subscribe to
Promise fullfilled with an object with the following keys:
- transactionId - The transaction/order id
- productId - productId purchased
- purchaseDate - purchase ISO date string format
- purchaseTime - purchase Timestamp
For example:
{
"productId": "com.mycompany.myproduct.weekly.v1",
"purchaseDate": "2017-04-18T09:19:41.000Z",
"purchaseTime": "1492507181",
"transactionId": "123412341234"
}[Require opened stargate,Return promise] Request subscription of In App Product on store
iap product id to subscribe to
If successful, the promise resolves to an object with the following attributes that you will need for the receipt validation:
- transactionId - The transaction/order id
- receipt - On iOS it will be the base64 string of the receipt, on Android it will be a string of a json with all the transaction details required for validation such as {"orderId":"...","packageName:"...","productId":"...","purchaseTime":"...", "purchaseState":"...","purchaseToken":"..."}
- signature - On Android it can be used to consume a purchase. On iOS it will be an empty string.
- productType - On Android it can be used to consume a purchase. On iOS it will be an empty string.
Receipt validation: - To validate your receipt, you will need the receipt and signature on Android and the receipt and transactionId on iOS.
For example:
var ResultAndroid = {
"signature":"base64encodedstring",
"productId":"product.id",
"transactionId":"fvjpwjfoviwjeovijwepvin",
"type":"subs",
"productType":"subs",
"receipt":"{\"packageName\":\"com.mycompany.myproduct\", \"productId\":\"product.id\", \"purchaseTime\":1510670063, \"purchaseState\":0, \"purchaseToken\":\"4rbQnUwZHb_wwZ\", \"autoRenewing\":true }"
};
var ResultIos = {
"transactionId": "1000000221696692",
"receipt": "base64encodedstring"
};[Require opened stargate,Return promise] Request restore of In App Products already purchased on store
If successful, the promise resolves to:
- false if no valid subscription restored
- {id: {...}} map of productId with valid subscription restored
For example:
false[Require opened stargate,Return promise] Request list of In App Products with an active subscription
If successful, the promise resolves to:
- {id: {...}} map of productId with active subscription
For example on Android:
{
"com.mycompany.myproduct.weekly.v1": {
"packageName": "com.mycompany.myproduct","productId": "com.mycompany.myproduct.weekly.v1",
"purchaseTime": 1491209382421,
"purchaseState": 0,
"purchaseToken": "nknmjmadpdhibpnaeibbxxxx",
"autoRenewing": true
}
}[Require opened stargate,Return promise] Return a promise returning a boolean that represent the subscription validity status. On iOS it execute the local decode of iOS receipt. On Android it perform a restore, than it check if there is the product requested and if it's valid.
iap product id subscribed to
Promise fullfilled with a Boolean that is the validity of the subscription of the requested productId
Usage example:
Stargate.iaplight.isSubscribed("com.mycompany.myproduct")
.then(function(subsciptionStatus){
console.log("Stargate.iaplight.isSubscribed",subsciptionStatus);
if ( subsciptionStatus ) {
console.log("SuscriptionOK")
} else {
console.warn("SubscriptionKO, request to pay!")
}
}).catch(function(err){
console.error( "Stargate.iaplight.isSubscribedERROR", err);
})android error codes:
public static final int INVALID_ARGUMENTS = -1;
public static final int UNABLE_TO_INITIALIZE = -2;
public static final int BILLING_NOT_INITIALIZED = -3;
public static final int UNKNOWN_ERROR = -4;
public static final int USER_CANCELLED = -5;
public static final int BAD_RESPONSE_FROM_SERVER = -6;
public static final int VERIFICATION_FAILED = -7;
public static final int ITEM_UNAVAILABLE = -8;
public static final int ITEM_ALREADY_OWNED = -9;
public static final int ITEM_NOT_OWNED = -10;
public static final int CONSUME_FAILED = -11;iOS error codes:
NSInteger const RMStoreErrorCodeDownloadCanceled = 300;
NSInteger const RMStoreErrorCodeUnknownProductIdentifier = 100;
NSInteger const RMStoreErrorCodeUnableToCompleteVerification = 200;common error codes:
101: 'invalid argument - productIds must be an array of strings',
102: 'invalid argument - productId must be a string',
103: 'invalid argument - product type must be a string',
104: 'invalid argument - receipt must be a string of a json',
105: 'invalid argument - signature must be a string',Errors arrive as objects like this:
{
errorCode: xxx,
code: xxx,
}[Require opened stargate,Return promise] Request an auto push (local notification) on a specific date
| Options key | Description | Example |
|---|---|---|
| title | [required] String title of notification | Stargate |
| text | [required] String text of notification | Check out this cool library for hybrid apps! |
| date | [required] Date when the notification will show up | new Date(new Date() + 5*1000) |
| deeplink | [required] String url of a specific webapp page | "http://www.stargate.com/#!/route/to/mypushedcontent" |
Promise fullfilled with boolean result status
@deprecated since 0.5.0
[Require opened stargate,Use callbacks] Facebook sharing
Parameter string url: shared url
[Require opened stargate,Use callbacks] IAP subscription
[Require opened stargate,Use callbacks] IAP restore
[Require opened stargate,Use callbacks] IAP product information
Call callbacks with information about a product got from store
productId - product id about to query for information on store
callbackSuccess - a function that will be called when information are ready
callbackError - a function that will be called in case of error
// example of object sent to success callback
{
"id": "stargate.test.spec.product1",
"alias": "Test Spec Product 1",
"title": "Test Spec Product 1",
"description": "Test Spec Product 1",
"currency": "EUR",
"price": "0,99 €",
"type": "paid subscription",
"canPurchase": true,
"downloaded": false,
"downloading": false,
"loaded": true,
"owned": false,
"state": "valid",
"transaction": null,
"valid": true
}[Require opened stargate] return {object} with this information:
| Value | Description |
|---|---|
| cordova | Cordova version |
| manufacturer | device manufacter |
| model | device model |
| platform | platform (Android, iOs, etc) |
| deviceId | device UUID |
| version | platform version |
| packageVersion | package version |
| packageName | package name ie: com.stargatejs.test |
| packageBuild | package build number |
| stargate | stargate version |
| stargateModules | modules initialized |
| stargateError | initialization error |
[Require opened stargate] return {array} with list of features available in native, defined in manifest.json inside the package
Inside manifest there is an object that holds all configuration options of Stargate. This configuration is loaded with ManifoldJS hostedwebapp plugin.
- Stargate.initialize() save user configuration sent as parameter and attach to the cordova deviceready event the internal function onDeviceReady()
- onDeviceReady() request all needed data from plugin and internal async modules; wait for all request to complete, save the data received and call onPluginReady()
- onPluginReady() is the main internal initialization function where all syncronous processing is performed
- build (default task)
- lint
- test
- karma (--browsers=[PhantomJS]|Chrome)
- watch
- github PR your feature branch to develop
- github PR develop to master
- git checkout master
- git pull
- npm version (minor|patch)
- git push
- git push --tags
==to automate==
Travis build the project on every push and check for lint and test errors. It also send the test coverage to coveralls.io
All public api of Stargate requires some cordova plugins to be available in the app. This is a list of the plugin used by the various function of Stargate:
| Functionality | Cordova plugin required |
|---|---|
| initialize | ManifoldJS D-Mobilelab fork |
| initialize | cordova-plugin-app-version |
| initialize | cordova-plugin-device |
| initialize | cordova-plugin-splashscreen |
| update offline files | cordova-plugin-code-push |
| iaplight | AlexDisler/cordova-plugin-inapppurchase |
| iap | j3k0/cordova-plugin-purchase |
| socialShare | EddyVerbruggen/SocialSharing-PhoneGap-Plugin |
| appsflyer | cordova-plugin-appsflyer |
| push | katzer/cordova-plugin-local-notifications |
We have an html page on www folder of cordova project that check if there is network connectivity and if so go to the webapp, where HostedWebApp will inject the cordova.js. If there isn't connectivity it goes to an offline version of the site, that can be only a message or can be a full app.
- git clone
- npm install
- bower install
- gulp build