From 65f9804cd5e9f5c6a6869999a7537ab10c618959 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Tue, 9 Jan 2024 07:43:11 +0200 Subject: [PATCH 01/13] intro template --- app-management/guides/About App Management.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 833134186a..f666962f79 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -1,4 +1,5 @@ # About App Management + The Wix App Management APIs provide your app with access to basic user data and specific app functionality. - The [App Instance API](https://dev.wix.com/api/rest/app-management/apps/app-instance/introduction) exposes basic data about the site and your app installed on it. @@ -6,3 +7,39 @@ The Wix App Management APIs provide your app with access to basic user data and - The [Embedded Scripts API](https://dev.wix.com/api/rest/app-management/apps/embedded-scripts/introduction) enables your app to inject custom script tags to the site's tag. - The [BI Events API](https://dev.wix.com/api/rest/app-management/apps/bi-event/introduction) enables your app to send BI events to the Wix system. - The [Editor Deep Link API](https://dev.wix.com/api/rest/app-management/about-the-editor-deep-link-api) (Beta) enables your app to link to a URL that hat opens the Editor and adds an app's Custom Element component to the site's page. + +# About the App Management API + +The App Management API allows you to handle data. + +With the {{AMAZING}} API, you can: + ++ Identify specific app instances ++ Manage usage-based pricing for your app ++ Add embedded scripts to Wix sites + +Learn more about: + ++ [Pricing options for your app](https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/set-up-your-app-pricing) ++ + +## Before you begin + +It’s important to note the following points before starting to code: + ++ Currently, ++ {{API consumers must know this before starting development}} + +## Use cases + ++ [{{Do this}}](link-to-the-relevant-flow) ++ [{{Do that}}](link-to-the-relevant-article) + +## Terminology + ++ __App Instance__: Unique identifier of an app within a specific website. The + app instance ID is ideal for identifying your users, the specific plan they’ve + purchased from you and the features you should be supporting for them. ++ __Usage-based pricing__: {{DEFINITION_2}} + + __Custom Charge__: {{DEFINITION_2A}} ++ __Embedded script__: {{DEFINITION_3}} \ No newline at end of file From 8506dfe680b5389a2be270a57d604d18454971a7 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Tue, 9 Jan 2024 12:37:58 +0200 Subject: [PATCH 02/13] Terminology --- app-management/guides/About App Management.md | 51 ++++++++++--------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index f666962f79..1fff2e0c5d 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -1,45 +1,46 @@ -# About App Management +# About the App Management APIs -The Wix App Management APIs provide your app with access to basic user data and specific app functionality. +The App Management APIs allow you to manage user specific data for all individual +installations of your app. This includes receiving notifications whenever a new +user installs your app on their site or purchases a Premium version. -- The [App Instance API](https://dev.wix.com/api/rest/app-management/apps/app-instance/introduction) exposes basic data about the site and your app installed on it. -- The [Billing API](https://dev.wix.com/api/rest/app-management/apps/billing/introduction) enables your app to lead customers seamlessly into Wix's checkout process from your platform. -- The [Embedded Scripts API](https://dev.wix.com/api/rest/app-management/apps/embedded-scripts/introduction) enables your app to inject custom script tags to the site's tag. -- The [BI Events API](https://dev.wix.com/api/rest/app-management/apps/bi-event/introduction) enables your app to send BI events to the Wix system. -- The [Editor Deep Link API](https://dev.wix.com/api/rest/app-management/about-the-editor-deep-link-api) (Beta) enables your app to link to a URL that hat opens the Editor and adds an app's Custom Element component to the site's page. +With the App Management APIs, you can: -# About the App Management API - -The App Management API allows you to handle data. - -With the {{AMAZING}} API, you can: - -+ Identify specific app instances -+ Manage usage-based pricing for your app -+ Add embedded scripts to Wix sites ++ [Track user specific data with app instance IDs](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/introduction) ++ [Manage usage-based pricing](https://dev.wix.com/docs/rest/api-reference/app-management/) ++ [Add embedded scripts to Wix sites](https://dev.wix.com/docs/rest/api-reference/app-management/apps/embedded-scripts/introduction) ++ [Notify Wix about your app's business events](https://dev.wix.com/docs/rest/api-reference/app-management/apps/bi-event/introduction) Learn more about: + [Pricing options for your app](https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/set-up-your-app-pricing) -+ ## Before you begin It’s important to note the following points before starting to code: -+ Currently, -+ {{API consumers must know this before starting development}} ++ You can't switch the pricing model of your app after the original set up. ++ Currently, there are no notifications about the payment status of an invoice. ## Use cases -+ [{{Do this}}](link-to-the-relevant-flow) -+ [{{Do that}}](link-to-the-relevant-article) ++ [Track new app instances](link-to-the-relevant-flow) ++ [Manage invoices with usage-based charges](link-to-the-relevant-article) ## Terminology + __App Instance__: Unique identifier of an app within a specific website. The app instance ID is ideal for identifying your users, the specific plan they’ve - purchased from you and the features you should be supporting for them. -+ __Usage-based pricing__: {{DEFINITION_2}} - + __Custom Charge__: {{DEFINITION_2A}} -+ __Embedded script__: {{DEFINITION_3}} \ No newline at end of file + purchased from you and the features you're supporting for them. ++ __App Pricing__: You can choose the business model that works best for your app: + + __Freemium__: We recommend to choose Freemium pricing. You offer both free + and paid versions of your app. Users can upgrade to Premium at any time. + + __Free__: You don't charge your users. + + __Premium__: Users must pay to use your app. + + __Pay as you go__: ??? + + __Usage-based pricing__: You charge your users on a recurring, monthly basis. + You can include a flat base fee and other fees if you want. + + __Combination of business models__: ??? + + __Custom Charge__: Adjustable price for using your app. Each billing cycle + you can add up to 5 charges to an invoice that Wix sends to your customer. ++ __Embedded script__: Script that you can add to a site's `` tag. \ No newline at end of file From 4f021b45b02948f105166c54b2d39257cfd3bee8 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 10 Jan 2024 09:05:26 +0200 Subject: [PATCH 03/13] use case headings --- app-management/guides/About App Management.md | 27 ++++++++++++++++--- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 1fff2e0c5d..9d51871f48 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -2,7 +2,8 @@ The App Management APIs allow you to manage user specific data for all individual installations of your app. This includes receiving notifications whenever a new -user installs your app on their site or purchases a Premium version. +user installs your app on their site or purchases a Premium version. Additionally, +you can use the APIs to add custom charges to your users' invoices. With the App Management APIs, you can: @@ -14,18 +15,36 @@ With the App Management APIs, you can: Learn more about: + [Pricing options for your app](https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/set-up-your-app-pricing) ++ [Setting up embedded scripts](https://dev.wix.com/docs/build-apps/developer-tools/extensions/embedded-scripts) ++ [Identifying users with App Instance ID](https://dev.wix.com/docs/build-apps/build-your-app/app-instance/identify-users-app-instance) ## Before you begin It’s important to note the following points before starting to code: -+ You can't switch the pricing model of your app after the original set up. -+ Currently, there are no notifications about the payment status of an invoice. ++ The Wix pricing page for your app supports only 4 plans for users to choose + from. This includes your app's free plan if you offer one. In case you want + to offer more than 4 plans, your app needs to build an external pricing + page and [redirect users back to the Wix checkout](https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/get-url). ++ You can't delete an app's pricing plan after you have set it up, but you can + add more plans. ++ Currently, Wix doesn't notify you about changes to the payment status of an + invoice. ## Use cases + [Track new app instances](link-to-the-relevant-flow) + -> listen to app installed webhook + save instance ID + Any app using REST apis must have OAUTh -> you get notified with access token (that includes app instance ID) + + If free version is installed -> reach out to user (Upgrade button/email/...) + [Manage invoices with usage-based charges](link-to-the-relevant-article) ++ [How can I tell Wix apps]() + Get App Instance -> installed Wix apps ++ [Automatically create user logins]() + get app instance -> ownerInfo.email (must have Read ... permission) + Ste up auto login on app's side ## Terminology @@ -37,7 +56,7 @@ It’s important to note the following points before starting to code: and paid versions of your app. Users can upgrade to Premium at any time. + __Free__: You don't charge your users. + __Premium__: Users must pay to use your app. - + __Pay as you go__: ??? + + __Pay as you go__: ??? External pricing for not supported models + __Usage-based pricing__: You charge your users on a recurring, monthly basis. You can include a flat base fee and other fees if you want. + __Combination of business models__: ??? From 13feaa897c5a1dc51c8b7db84b566da30d2b96a9 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 10 Jan 2024 10:38:51 +0200 Subject: [PATCH 04/13] initial use cases --- app-management/guides/About App Management.md | 16 +--- .../guides/AppManagementSampleFlows.md | 85 +++++++++++++++++++ 2 files changed, 89 insertions(+), 12 deletions(-) create mode 100644 app-management/guides/AppManagementSampleFlows.md diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 9d51871f48..2e988b2ddf 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -33,18 +33,10 @@ It’s important to note the following points before starting to code: ## Use cases -+ [Track new app instances](link-to-the-relevant-flow) - -> listen to app installed webhook - save instance ID - Any app using REST apis must have OAUTh -> you get notified with access token (that includes app instance ID) - - If free version is installed -> reach out to user (Upgrade button/email/...) -+ [Manage invoices with usage-based charges](link-to-the-relevant-article) -+ [How can I tell Wix apps]() - Get App Instance -> installed Wix apps -+ [Automatically create user logins]() - get app instance -> ownerInfo.email (must have Read ... permission) - Ste up auto login on app's side ++ [Encourage new users to upgrade](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#encourage-new-users-to-upgrade) ++ [Manage invoices with usage-based charges](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#bill-a-customer) ++ [Identify a site's installed Wix business solutions](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#identify-a-sites-installed-wix-business-solutions) ++ [Automatically create user login](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#automatically-create-user-login) ## Terminology diff --git a/app-management/guides/AppManagementSampleFlows.md b/app-management/guides/AppManagementSampleFlows.md new file mode 100644 index 0000000000..c5504bbd99 --- /dev/null +++ b/app-management/guides/AppManagementSampleFlows.md @@ -0,0 +1,85 @@ +# App Management: Sample Use Cases and Flows + +This article shares some possible use cases your app could support, as well as +a sample flow that could support each use case. This can be a helpful jumping +off point as you plan your app's implementation. + +## Encourage new users to upgrade + +You could reach out to new users who install the free version of your app and +encourage them to upgrade. + +To encourage upgrades: + +1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) + webhook. Make sure to save the `data.instanceId` from the payload. +1. Pass the `instanceID` when calling + [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance). +1. In the response data, confirm that the site owner's have installed the free + version of your app by checking `instance.isFree`. Also save the site owner's + email, you can find it in `instance.ownerInfo.email`. + Make sure to confirm that the user has opted in to receive communication by + checking that `instance.ownerInfo.emailStatus` is either `"VERIFIED_OPT_IN"` or + `"NOT_VERIFIED_OPT_IN"`. Note that you must have added the + __Read Site Owner Email__ permission scope to your app during the setup + process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). + In case you, haven't requested this permission, the `ownerInfo` object is + always returned empty. +1. In case the owner's have opted in to receive notifications, send them an email that includes a link to the + [Upgrade Button](). +1. Listen to the [Paid Plan Purchased](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/paid-plan-purchased) + webhook to get notified about the upgrade. + +We recommend signing up for the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) +webhook. In case your app is using Wix REST APIs, you would also receive an +access token that includes the app instance ID during the +[OAuth setup](https://dev.wix.com/docs/rest/articles/getting-started/authentication#the-oauth-flow), +but listening to the webhook ensures the installation process has succeeded. + +## Identify a site's installed Wix business solutions + +In case your app requires that the site owners have also installed a specific +[Wix business solution](https://dev.wix.com/docs/rest/articles/getting-started/wix-business-solutions), +you can verify that the relevant app is installed on that site. During your app's +setup process in the Developers Center you can mark one or more Wix app's as +requirements, but we recommend to follow this flow since you may support different use +cases, depending on which Wix app is installed. For example, your app may support +different use cases, depending on whether the site includes [Wix Stores](https://www.wix.com/app-market/wix-stores?referral=collection&appIndex=2&referralTag=made-by-wix&referralSectionName=made-by-wix) +or [Wix Bookings](https://www.wix.com/app-market/bookings?referral=collection&appIndex=6&referralTag=made-by-wix&referralSectionName=made-by-wix). + +To Identify a site's installed Wix apps: + +1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) + webhook. Make sure to save the `data.instanceId` from the payload. +1. Pass the `instanceID` when calling + [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) + to retrieve installed Wix apps. You can find them as human-readable names in + the `site.installedWixApps` array. In case your app supports multiple use cases, + see if you can identify the user's intent from the list of returned apps alone. +1. Optional: If they have installed multiple Wix apps for which you support + different flows, reach out to the site owner to check their preference. Make + sure to confirm that the user has opted in to receive communication by + checking that `ownerInfo.emailStatus` is either `"VERIFIED_OPT_IN"` or + `"NOT_VERIFIED_OPT_IN"`. Note that you must have added the + __Read Site Owner Email__ permission scope to your app during the setup + process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). + In case you, haven't requested this permission, the `ownerInfo` object is + always returned empty. + +## Automatically create user login + +You could automatically create a user login for new customers of your app. + +To create user logins: + +1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) + webhook. Make sure to save the `data.instanceId` from the payload. +1. Pass the `instanceID` when calling + [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) + to retrieve the site owner's email, you can find it in `instance.ownerInfo.email`. + Note that you must have added the + __Read Site Owner Email__ permission scope to your app during the setup + process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). + In case you, haven't requested this permission, the `ownerInfo` object is + always returned empty. +1. Set up the automatic user login on your app's side. \ No newline at end of file From 9045f04b53fd9c3283641beb86b91b737cf8801b Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 10 Jan 2024 14:39:10 +0200 Subject: [PATCH 05/13] use case adjustments --- app-management/guides/About App Management.md | 6 ++--- .../guides/AppManagementSampleFlows.md | 23 +++++++++++-------- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 2e988b2ddf..8ae6f2f61d 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -33,10 +33,10 @@ It’s important to note the following points before starting to code: ## Use cases -+ [Encourage new users to upgrade](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#encourage-new-users-to-upgrade) -+ [Manage invoices with usage-based charges](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#bill-a-customer) ++ [Reach out to new users](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#reach-out-to-new-users) ++ [Manage usage-based invoices](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#bill-a-customer) + [Identify a site's installed Wix business solutions](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#identify-a-sites-installed-wix-business-solutions) -+ [Automatically create user login](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#automatically-create-user-login) ++ [Automatically create user logins](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#automatically-create-user-logins) ## Terminology diff --git a/app-management/guides/AppManagementSampleFlows.md b/app-management/guides/AppManagementSampleFlows.md index c5504bbd99..3023105607 100644 --- a/app-management/guides/AppManagementSampleFlows.md +++ b/app-management/guides/AppManagementSampleFlows.md @@ -4,20 +4,21 @@ This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation. -## Encourage new users to upgrade +## Reach out to new users -You could reach out to new users who install the free version of your app and -encourage them to upgrade. +You could reach out to your app's new users. For example, you could encourage +free users to upgrade their version. -To encourage upgrades: +To reach out to new users: 1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) webhook. Make sure to save the `data.instanceId` from the payload. 1. Pass the `instanceID` when calling [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance). -1. In the response data, confirm that the site owner's have installed the free - version of your app by checking `instance.isFree`. Also save the site owner's - email, you can find it in `instance.ownerInfo.email`. +1. Optional: In the response data, confirm that the site owner's have installed the free + version of your app by checking `instance.isFree`. You may use this information + to encourage them to upgrade. +1. Save the site owner's email, you can find it in `instance.ownerInfo.email`. Make sure to confirm that the user has opted in to receive communication by checking that `instance.ownerInfo.emailStatus` is either `"VERIFIED_OPT_IN"` or `"NOT_VERIFIED_OPT_IN"`. Note that you must have added the @@ -25,9 +26,11 @@ To encourage upgrades: process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). In case you, haven't requested this permission, the `ownerInfo` object is always returned empty. -1. In case the owner's have opted in to receive notifications, send them an email that includes a link to the +1. Optional: In case the owner's have opted in to receive notifications, send + them an email that includes a link to the [Upgrade Button](). -1. Listen to the [Paid Plan Purchased](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/paid-plan-purchased) + Then, you could listen to the + [Paid Plan Purchased](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/paid-plan-purchased) webhook to get notified about the upgrade. We recommend signing up for the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) @@ -66,7 +69,7 @@ To Identify a site's installed Wix apps: In case you, haven't requested this permission, the `ownerInfo` object is always returned empty. -## Automatically create user login +## Automatically create user logins You could automatically create a user login for new customers of your app. From d950dcd321c3773c24123197d20a4cf00b5243ed Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Tue, 16 Jan 2024 09:15:41 +0200 Subject: [PATCH 06/13] Sample flow ideas --- app-management/guides/About App Management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 8ae6f2f61d..e1cba93290 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -14,9 +14,9 @@ With the App Management APIs, you can: Learn more about: ++ [Identifying users with App Instance ID](https://dev.wix.com/docs/build-apps/build-your-app/app-instance/identify-users-app-instance) + [Pricing options for your app](https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/set-up-your-app-pricing) + [Setting up embedded scripts](https://dev.wix.com/docs/build-apps/developer-tools/extensions/embedded-scripts) -+ [Identifying users with App Instance ID](https://dev.wix.com/docs/build-apps/build-your-app/app-instance/identify-users-app-instance) ## Before you begin From c7d115c6db26d1f969de6f256235c3b0d5b4462b Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 09:03:56 +0200 Subject: [PATCH 07/13] Use case changes --- app-management/guides/About App Management.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index e1cba93290..0e4d41f3d4 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -22,15 +22,13 @@ Learn more about: It’s important to note the following points before starting to code: ++ Currently, Wix doesn't notify you about changes to the payment status of an + invoice. + The Wix pricing page for your app supports only 4 plans for users to choose from. This includes your app's free plan if you offer one. In case you want to offer more than 4 plans, your app needs to build an external pricing page and [redirect users back to the Wix checkout](https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/get-url). -+ You can't delete an app's pricing plan after you have set it up, but you can - add more plans. -+ Currently, Wix doesn't notify you about changes to the payment status of an - invoice. - + ## Use cases + [Reach out to new users](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#reach-out-to-new-users) From 4bcb238ac71dbcaec6954626523dc77927be7f79 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 09:31:10 +0200 Subject: [PATCH 08/13] auto login motivation --- app-management/guides/About App Management.md | 2 +- app-management/guides/AppManagementSampleFlows.md | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 0e4d41f3d4..cf6ff4b36f 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -34,7 +34,7 @@ It’s important to note the following points before starting to code: + [Reach out to new users](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#reach-out-to-new-users) + [Manage usage-based invoices](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#bill-a-customer) + [Identify a site's installed Wix business solutions](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#identify-a-sites-installed-wix-business-solutions) -+ [Automatically create user logins](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#automatically-create-user-logins) ++ [Automatically log users in to your app](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/sample-flows#automatically-log-users-in-to-your-app) ## Terminology diff --git a/app-management/guides/AppManagementSampleFlows.md b/app-management/guides/AppManagementSampleFlows.md index 3023105607..65643881f7 100644 --- a/app-management/guides/AppManagementSampleFlows.md +++ b/app-management/guides/AppManagementSampleFlows.md @@ -69,9 +69,12 @@ To Identify a site's installed Wix apps: In case you, haven't requested this permission, the `ownerInfo` object is always returned empty. -## Automatically create user logins +## Automatically log users in to your app -You could automatically create a user login for new customers of your app. +You could automatically create a user login for new customers of your app. Then, +site owners don't need to set up an account for your app on their own. They could +also share their account for your app with multiple contributors without being +forced to share sensitive login info. To create user logins: From d7746289e7052ccde9cf871318d873df94130cf4 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 09:38:16 +0200 Subject: [PATCH 09/13] Adjusted Wix App flow --- app-management/guides/AppManagementSampleFlows.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/app-management/guides/AppManagementSampleFlows.md b/app-management/guides/AppManagementSampleFlows.md index 65643881f7..9494094eb1 100644 --- a/app-management/guides/AppManagementSampleFlows.md +++ b/app-management/guides/AppManagementSampleFlows.md @@ -58,16 +58,10 @@ To Identify a site's installed Wix apps: [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) to retrieve installed Wix apps. You can find them as human-readable names in the `site.installedWixApps` array. In case your app supports multiple use cases, - see if you can identify the user's intent from the list of returned apps alone. -1. Optional: If they have installed multiple Wix apps for which you support - different flows, reach out to the site owner to check their preference. Make - sure to confirm that the user has opted in to receive communication by - checking that `ownerInfo.emailStatus` is either `"VERIFIED_OPT_IN"` or - `"NOT_VERIFIED_OPT_IN"`. Note that you must have added the - __Read Site Owner Email__ permission scope to your app during the setup - process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). - In case you, haven't requested this permission, the `ownerInfo` object is - always returned empty. + check if you can identify the user's intent from the list of returned apps alone. +1. If you can't identify the desired use case because the site owners have installed + multiple Wix apps for which you support different flows, present a modal to + them that lets them choose their preference. ## Automatically log users in to your app From 8d0a4dda31c63d122c51ffc8053cdc9733d69d05 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 15:33:01 +0200 Subject: [PATCH 10/13] terminology reorg --- app-management/guides/About App Management.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index cf6ff4b36f..33b7deae68 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -41,15 +41,11 @@ It’s important to note the following points before starting to code: + __App Instance__: Unique identifier of an app within a specific website. The app instance ID is ideal for identifying your users, the specific plan they’ve purchased from you and the features you're supporting for them. -+ __App Pricing__: You can choose the business model that works best for your app: - + __Freemium__: We recommend to choose Freemium pricing. You offer both free - and paid versions of your app. Users can upgrade to Premium at any time. - + __Free__: You don't charge your users. - + __Premium__: Users must pay to use your app. - + __Pay as you go__: ??? External pricing for not supported models ++ __App Pricing__: You can choose the business model that works best for your app. + Use the [Custom Charges SPI](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/introduction) + to manage your app's usage-based pricing. + __Usage-based pricing__: You charge your users on a recurring, monthly basis. You can include a flat base fee and other fees if you want. - + __Combination of business models__: ??? + __Custom Charge__: Adjustable price for using your app. Each billing cycle you can add up to 5 charges to an invoice that Wix sends to your customer. + __Embedded script__: Script that you can add to a site's `` tag. \ No newline at end of file From 4586d9711c86896d373fad2738e8dc36433097a5 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 15:33:20 +0200 Subject: [PATCH 11/13] removed before you begin --- app-management/guides/About App Management.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 33b7deae68..8740607275 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -17,17 +17,6 @@ Learn more about: + [Identifying users with App Instance ID](https://dev.wix.com/docs/build-apps/build-your-app/app-instance/identify-users-app-instance) + [Pricing options for your app](https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/set-up-your-app-pricing) + [Setting up embedded scripts](https://dev.wix.com/docs/build-apps/developer-tools/extensions/embedded-scripts) - -## Before you begin - -It’s important to note the following points before starting to code: - -+ Currently, Wix doesn't notify you about changes to the payment status of an - invoice. -+ The Wix pricing page for your app supports only 4 plans for users to choose - from. This includes your app's free plan if you offer one. In case you want - to offer more than 4 plans, your app needs to build an external pricing - page and [redirect users back to the Wix checkout](https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/get-url). ## Use cases From d604f9b80fa6872706cff30e9ff942166d6b06c7 Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 15:36:13 +0200 Subject: [PATCH 12/13] rephrased into paragraph --- app-management/guides/About App Management.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/app-management/guides/About App Management.md b/app-management/guides/About App Management.md index 8740607275..a473ef1d37 100644 --- a/app-management/guides/About App Management.md +++ b/app-management/guides/About App Management.md @@ -3,12 +3,13 @@ The App Management APIs allow you to manage user specific data for all individual installations of your app. This includes receiving notifications whenever a new user installs your app on their site or purchases a Premium version. Additionally, -you can use the APIs to add custom charges to your users' invoices. +you can use the APIs to implement an external pricing page and manage usage-based +pricing. With the App Management APIs, you can: + [Track user specific data with app instance IDs](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/introduction) -+ [Manage usage-based pricing](https://dev.wix.com/docs/rest/api-reference/app-management/) ++ [Manage usage-based pricing](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/introduction) + [Add embedded scripts to Wix sites](https://dev.wix.com/docs/rest/api-reference/app-management/apps/embedded-scripts/introduction) + [Notify Wix about your app's business events](https://dev.wix.com/docs/rest/api-reference/app-management/apps/bi-event/introduction) From 5b37dcc8fc561ad17d7acd496afd4e53180bc92c Mon Sep 17 00:00:00 2001 From: SimonC24 Date: Wed, 17 Jan 2024 15:46:56 +0200 Subject: [PATCH 13/13] Removed sample flows --- .../guides/AppManagementSampleFlows.md | 85 ------------------- 1 file changed, 85 deletions(-) delete mode 100644 app-management/guides/AppManagementSampleFlows.md diff --git a/app-management/guides/AppManagementSampleFlows.md b/app-management/guides/AppManagementSampleFlows.md deleted file mode 100644 index 9494094eb1..0000000000 --- a/app-management/guides/AppManagementSampleFlows.md +++ /dev/null @@ -1,85 +0,0 @@ -# App Management: Sample Use Cases and Flows - -This article shares some possible use cases your app could support, as well as -a sample flow that could support each use case. This can be a helpful jumping -off point as you plan your app's implementation. - -## Reach out to new users - -You could reach out to your app's new users. For example, you could encourage -free users to upgrade their version. - -To reach out to new users: - -1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) - webhook. Make sure to save the `data.instanceId` from the payload. -1. Pass the `instanceID` when calling - [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance). -1. Optional: In the response data, confirm that the site owner's have installed the free - version of your app by checking `instance.isFree`. You may use this information - to encourage them to upgrade. -1. Save the site owner's email, you can find it in `instance.ownerInfo.email`. - Make sure to confirm that the user has opted in to receive communication by - checking that `instance.ownerInfo.emailStatus` is either `"VERIFIED_OPT_IN"` or - `"NOT_VERIFIED_OPT_IN"`. Note that you must have added the - __Read Site Owner Email__ permission scope to your app during the setup - process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). - In case you, haven't requested this permission, the `ownerInfo` object is - always returned empty. -1. Optional: In case the owner's have opted in to receive notifications, send - them an email that includes a link to the - [Upgrade Button](). - Then, you could listen to the - [Paid Plan Purchased](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/paid-plan-purchased) - webhook to get notified about the upgrade. - -We recommend signing up for the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) -webhook. In case your app is using Wix REST APIs, you would also receive an -access token that includes the app instance ID during the -[OAuth setup](https://dev.wix.com/docs/rest/articles/getting-started/authentication#the-oauth-flow), -but listening to the webhook ensures the installation process has succeeded. - -## Identify a site's installed Wix business solutions - -In case your app requires that the site owners have also installed a specific -[Wix business solution](https://dev.wix.com/docs/rest/articles/getting-started/wix-business-solutions), -you can verify that the relevant app is installed on that site. During your app's -setup process in the Developers Center you can mark one or more Wix app's as -requirements, but we recommend to follow this flow since you may support different use -cases, depending on which Wix app is installed. For example, your app may support -different use cases, depending on whether the site includes [Wix Stores](https://www.wix.com/app-market/wix-stores?referral=collection&appIndex=2&referralTag=made-by-wix&referralSectionName=made-by-wix) -or [Wix Bookings](https://www.wix.com/app-market/bookings?referral=collection&appIndex=6&referralTag=made-by-wix&referralSectionName=made-by-wix). - -To Identify a site's installed Wix apps: - -1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) - webhook. Make sure to save the `data.instanceId` from the payload. -1. Pass the `instanceID` when calling - [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) - to retrieve installed Wix apps. You can find them as human-readable names in - the `site.installedWixApps` array. In case your app supports multiple use cases, - check if you can identify the user's intent from the list of returned apps alone. -1. If you can't identify the desired use case because the site owners have installed - multiple Wix apps for which you support different flows, present a modal to - them that lets them choose their preference. - -## Automatically log users in to your app - -You could automatically create a user login for new customers of your app. Then, -site owners don't need to set up an account for your app on their own. They could -also share their account for your app with multiple contributors without being -forced to share sensitive login info. - -To create user logins: - -1. Listen to the [Instance App Installed](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/instance-app-installed) - webhook. Make sure to save the `data.instanceId` from the payload. -1. Pass the `instanceID` when calling - [Get App Instance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) - to retrieve the site owner's email, you can find it in `instance.ownerInfo.email`. - Note that you must have added the - __Read Site Owner Email__ permission scope to your app during the setup - process in the [Wix Developers Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app#4-add-permissions). - In case you, haven't requested this permission, the `ownerInfo` object is - always returned empty. -1. Set up the automatic user login on your app's side. \ No newline at end of file