This article Contain FULL partner API, but you only need this API if you create apps in bulk integrated with your other software solution!!!
For standard Partner reselling of 1-5 apps a day it makes no sense to integrate this API, as it is quicker to create such apps manually.
NOTE - THE API IS FOR WRAPPER ONLY FOR NOW. THE API FOR JS CAPSULE IS IN WORKS.
Overall steps
You will need to:
- Complete basic auth to recieve JWT tokens
- Refresh JWT tokens according to our general API policy, as with any other Mobsted API call
- Use the methods described below to create our PWAless wrapping for the websites you need.
The overall logic is on a drawing below:
Your partner Mobsted account has ability to create PWA container apps in two ways:
- inside of your partner master account, all apps will be accessible from the same account, or
- create client accounts, and then create PWA container apps inside those accounts
NOTE - System app ID 1 in your Master account - is an important part of the system, which tracks all your “client accounts”, so please make sure you do not delete or modify that app in any way.
______________
(A) Pre-step: Authenticate your API calls
Use standard Mobsted methods to get JWT auth tokens for your API calls. After getting JWT tokens, use these tokens to perform the rest of “Web to PWA” APIs.
To receive JWT tokens, use the following API method with the login and password from your Mster account, an example:
GET https://ppp-admin.mobsted.com/api/v8/[email protected]&password=12
GET https://ppp-admin.mobsted.com/api/v8/[email protected]&password=1234567
Where:
- “PPP-admin.mobsted.com” = is the address of your server and your account at our server, provided by our team
- "login" is the email you use to login into partner account
- "password" is the password you use to login into partner account
Receive access_token & refresh_token from response:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJwcHAtYWRtaW4ubWJzdC54eXoiLCJuYmxxxxxxxxxxxxxxxxxxxU5OTA0OTIwMywidWlkIjoiMmIzZTRiN2ItODVjOC00MzEwLWE4MTctM2FlMGJiYzQyMWJmIiwic3ViIjoiYXBpIiwib2JqdXVpZCI6IiIsInVzZXJ1dWlkIjoiMTdmZWU2YTUtZDk4My00OWZkLTg4OWMtMWI1NjlkMTg3YWNmIn0.eVOoDwJ7yh_TVb2j7FW7_jsTKT_SMJ8CFL10NX6RyXQ",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJwcHAtYWRtaW4ubWJzdC54eXoiLCJuYmYiOjE1OTg0NDQ0MDMsImV4cCI6MTYwMDg2MzYwMywidWlkIjoiMmIzZTRiN2ItODVjOC00MzEwLWE4MTctM2FlMGJiYzQyMWJmIiwic3ViIjoiYXBpIiwib2JqdXVpZCI6IiIsInVzZXJ1dWlkIjoiMTdmZWU2YTUtZDk4My0xxxxxxxxxxxxxxxxjlkMTg3YWNmIn0.MDLMOEAE1ATYPBtMLsYCf2T8wzaYqNkB_1NSDsmLx_4",
"expires_in": 1599049203
}
When sending the authenticated request, use the ACESS_TOKEN in the auth header:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJwcHAtYWRtaW4ubWJzdC54eXoiLCJuYmYiOjE1OTg0xxxxxxxxxxxxxxxxxxxxxywidWlkIjoiMmIzZTRiN2ItODVjOC00MzEwLWE4MTctM2FlMGJiYzQyMWJmIiwic3ViIjoiYXBpIiwib2JqdXVpZCI6IiIsInVzZXJ1dWlkIjoiMTdmZWU2YTUtZDk4My00OWZkLTg4OWMtMWI1NjlkMTg3YWNmIn0.eVOoDwJ7yh_TVb2j7FW7_jsTKT_SMJ8CFL10NX6RyXQ
You can perform this auth action, starting with account’s login and password before every “client account/app” creation, but we advise to set up automatic JWT tokens refresh on your backend.
___________
#1 API call - create a Client account/tenant
This method is called in contexts of your Master account/tenant, meaning using API address and tokens from your Master. This method only work if our team marked your account as Master/Partner.
POST https://ppp-admin.mbst.xyz/api/v8/partners
Type of parameters: raw (json)
An example:
{
"email": "[email protected]"
}
Where, email is the email of who will access this new Client Account. It has to be a new unique email for every new sub account/tenant.
The result of this API call has two parts:
(a) API response with auth data for that account, which you can store in your system, to match IDs of your sub accounts to your clients. An example:
“url”: “https://a23r56k8-admin.mobsted.com”,
"authentication": {
"email": "[email protected]",
"phone": "",
"password": "10ce7d73ae5fcc39g7064adc1ad03a03"
Where, URL contains the end point for all further API calls and for manual entry to the sub-account; authentication - logins and passwords for it.
(b) new Client Account/Tenant is recorded into Object’s table of your Master App ID=1, with the following fields:
- ServerName (i.e. mobsted.com), TenantName (i.e a23r56k8), UserLogin = email, UserPassword.
This is done so you may not create any additional storage in your backend, but have access to all you sub-accounts visually or by API.
To use all other API methods, including to create an app in THAT NEW ACCOUNT, you need to receive JWT tokens for each of those accounts using the PRE-STEP above with address and login-password pair for that sub account.
____________
#2 Creating the Wrapper Type App in Master or Client sub-account
Call this method in the context of either Master or Client account, depending on where you wish to create a PWA container app. Meaning - use address and auth tokens of the right account (Master or Client). Use only JWT tokens from method (A) above, for the targeted account.
POST https://ppp-admin.mbst.xyz/api/v8/partnerapps Type of paremeters: form-data Sample: name = App1 description = new pwaless application title = App1 splashColor = #dbdbdb panelColor = #ffffff isPWAless = 1 webSiteUrl = https://app1.com icon = (attached file) widgetDescription = <div style="font-family: Roboto, -apple-system, "Helvetica Neue", Helvetica, Arial, sans-serif; color: rgb(68, 68, 68);"><h3>Hi!</h3>This is a description to widget.</div> pushWidgetDescription = html code for text to ask for push channels saveWidgetDescription = html code for text to add to home screen text
PLEASE NOTE - there are 3 similar fields with a family name “Widget”.
The first - widgetDescription fills up data for the instant app saving prompt; second and third - pushWidgetDescription and saveWidgetDescription REPLACE default generic context of the managed prompts, created in each app automatically. These Push and Save fields ARE NOT REQUIRED to create an app, but we highly recommend filling these up as well, as changing it latter is slow and cumbersome..
The INSTANT method is enough for the most cases, but if you need to offer different context for saving the app, you could use MANAGED prompts and all it at the right times when needed, using API а call #4 below. Here is a useful table summarizing which prompt works where. If you need more than one context for Push prompt - contact our support.
All three fields accept HTML only and the code example you see above would provide the following app saving prompts if you put it into WidgetDescription or saveWidgetDescription:
The response to the call is:
{
"meta": {
"applications": {
"affected": 1,
"time": 0.84383988380432129
},
"applicationId": 78
},
"data": [
{
"id": "78",
"type": "applications",
"attributes": {
"ShortCodeUrl": "https://w2m.local/woAlF",
"QRCodeUrl": "/tenants/ppp/qr/78/qr.png",
"DateCreate": "2020-09-01 09:50:18.107369",
"ThumbImageUrl": "/tenants/ppp/iconapp/78/icon192x192.png",
"uuid": "a0581239-2029-489e-a213-08337ae121da",
"LonglinkInstant": "https://ppp.mobsted.com/?appid=78",
"LonglinkManaged": "https://ppp.mobsted.com/78?appid=78"
}
}
]
}
Note, that you get:
- full list of link to forward people to saving the app - here is an article on using these links in you system - https://docs.mobsted.com/display/KB/Direct+users+to+the+app
- unique ID of each app, so in case you wish to store matching pairs between your clients and container apps you could use “applicationId” or “id” (these are the same).
___________
#3 Searching for previously created sub-accounts/tenants
In case you create apps in sub accounts and do not store any info at your backend, you will need to create apps in it using those accounts login/pass pairs. To find the sub account you pre-created use the following method:
This method looks up a sub account in app ID=1 of your master account and returns its data. Call this from the Master account:
GET https://ppp-admin.mobsted.com/api/v8/object?applicationId=1&page=1&pageSize=100&query=[{"field": "Email", "operation": "=", "value": "[email protected]", "andor": "and"}]
Where,
applicationId: app ID where sub account records are stored - always =1
page: number of the page of records, but with unique email - always =1
pageSize: anything here, as there is only one record to be returned
query: fields to setup which email to filter out, contains JSON, use as shown.
The response will contain loads of different system fields for the app, you ONLY NEED the following ones for the purpose of this API:
"data": [
{
"id": "1",
"Email": "[email protected]",
"ServerName": null,
"TenantName": null,
"UserLogin": null,
"UserPassword": null,
}
}
]
___________
#4 Calling the “Managed” prompt/widget for Push and or Saving the app
This method is mostly needed for receiving Push permissions from a user, but is standard to call both Push and Saving prompts, when a user is inside the PWA container. It is a call from your resource to the container itself.
As mentioned, there are 3 prompts/widgets auto created for every new app, one INSTANT and 2 MANAGED (push and save). These later 2 have a generic meaning and text, but you can change it upon app creating using method #2, or later by manually login into the needed sub-account/app.
When user followed the link to the container or opened an app, already installed you have access to JS API to call these prompts/widgets:
parent.postMessage({ type: 'mobsted.api', showwidget: 'push' }, '*')
Where,
type: always “mobsted.api”
showwidget: user a code-name for the widget ( ‘push’ and ‘save’ are default code names for the 2 pre-created ones), or you can find it in the platform (red mark ↓), when you add more prompts:
If you need to close the prompt/widget that you have just opened, use the following:
parent.postMessage({ type: 'mobsted.api', hidewidget: 'push' }, '*'),
______________
#5 Detecting if an App was already installed on the device's home screen.
You need this method in case you want to hide “Save our app” type buttons and popups at your website’s interface, when people who already installed the app are on your website or visiting the container from it’s weblink, not from an icon.
This method works both in the context of your website and when a user is in the app's PWA container, IF you pass user IDs for the Mobsted PWA container to match who is who.
To pass your ID to the app container to record it you simply add utm_extid to every link a user visits before installing the app:
https://ppp.mobsted.com/pwa/?appid=<some-app-id>&utm_extid=<some-user-id>
Where EXTID is any kind of your internal user/session ID for this Client's website.
NOTE - in this case a request is sent directly to the app, not to the admin backend, SO without the “-admin” appendix.
The mechanics of this is the following - when a NEW user enters the app's container using the app’s link - Mobsted creates a new user record, which is assigned with the EXTID, which you pass to the link, as shown above. Every next entry of the same user - the existing user record is used, no new one is created.
To determine if the app was already installed to the home screen, you need to perform 2 actions:
(1) Connect the following script at the HEAD section of client’s website:
<script src="https://ppp-admin.mobsted.com/pwa/mobsted.pwa.js" type="text/javascript"></script>
(2) Call the following JavaScript at the moment you need to check for installation:
const result = await window.mbst.checkPwaInstalled(<your-user-EXTID>) or let result = false window.mbst.checkPwaInstalled(<your-user-EXTID>).then(val => (result = val))
Where:
<your-user-EXTID>: is your unique user IDentify on the client’s website, which you did pass as utm_extid
The response:
true = pwa is 100% installed, or false = not installed for the EXTID
NOTE - The only 100% fact of the app installed is at least one entry to the app by the user for both Android and iOS. All other data on installation differs in meaning between various versions of OS/browser combinations and are intentionally left out of the response
____________
#6 Sending Push messages to your users
There is a separate article on this subject - here.
Note, that you only send push if you assigned users their IDs to begin with using the "extid" function.