Receiving events when an app is installed

rafael.camargo · August 2, 2022, 6:38pm

Idea:

My main idea and objective with it are to create and publish apps to the app-store, but more complex applications that require, Master Data schemas and initial setups, really need that to be automatic, ideally once at install, or they will just not be as “plug-n-play” as the way they were meant to be.

Reference:

As I was browsing through the VTEX-apps repositories, I found out that in this external-promotion-provider-middleware the setup was made, basically exactly how I was imagining…

github.com

vtex-apps/external-promotion-provider-middleware/blob/main/node/service.json#L18


      
          "routes": {
            "orderFormNotification": {
              "path": "/_v/promotion-provider/notification",
              "public": true
            },
            "simulation": {
              "path": "/_v/promotion-provider/simulation",
              "public": true
            }
          },
          "events": {
            "onAppInstalled": {
              "sender": "apps",
              "keys": ["setup"],
              "settingsType": "workspace"
            },
            "onSettingsChanged": {
              "sender": "apps",
              "keys": ["settings"]
            }
          }

Problem:

The conclusion for it was that I tried to recreate the following onAppInstalled event, but with no success.

github.com

vtex-apps/external-promotion-provider-middleware/blob/main/node/middlewares/setupAppConfiguration.ts

import { orderFormConfigurationConstant } from '../constants/orderFormConfiguration'
import { orderFormConfiguration } from '../services'

const setupAppConfiguration = async (
  ctx: InstalledAppEvent,
  next: () => Promise<any>
) => {
  const { checkout } = ctx.clients

  try {
    await orderFormConfiguration.setConfiguration({
      client: checkout,
      configuration: orderFormConfigurationConstant,
    })
  } catch (error) {
    ctx.vtex.logger.error({
      setupAppConfigurationError: {
        status: 'failed',
        content: error,
      },

This file has been truncated. show original

Final thoughts:

I’m wondering if I need any specific permission to receive these events, or even if they’re just sent by the VTEX App Store, bc I tried to install via the CLI, with leaves me thinking this is only dispatched by the apps-store, but these are only theories…

Saito · August 2, 2022, 9:31pm

My wild guess:

onAppInstalled is triggered when the application is installed using the Admin.
onSettingsChanged is triggered when the user changes the app configuration in the admin.

Try change something in the https://{{accountName}}.myvtex.com/admin/apps (your app) settings and see if the onSettingsChanged → setupAppConfiguration function is called.

Also make sure that node/index.ts has the events definition.

Hope this helps!

georgebrindeiro · August 2, 2022, 11:53pm

I think @Saito is right, but I still need to test it to be sure.

If you are unable to make it work, you can always try the approach used by vtex-apps/easy-setup: have your users click a nice big button in your UI that runs all the setup routines you need.

In many cases that is better, because the user is aware of the changes you are making and you can guide them through what each one of them allows your app to do.

rafael.camargo · August 3, 2022, 12:15am

Yeap, the majority of your guesses are right, I spent time testing this a while ago. The settings change event works as expected, using the admin UI to change the settings it reflects in pretty much real-time. That’s for sure.

But with the onInstall that leaves the doubt, I tried some approaches to installing an app, but, none of the ways, using the CLI, dispatched the event, I tried just releasing and installing in the workspace, at master, and production just to name a few. But releasing to the store is one of the remaining tests i was not able to perform yet.

rafael.camargo · August 3, 2022, 12:30am

That’s our approach for now, for sure, in applications and settings that cause major changes or even, relevant events in the store that’s the better way to drive it.

chrome-capture-2022-7-2

A demo for an easing and intuitive setup.

But when we talk about some unique events, that don’t “add” to the user experience, saving some time and additional steps would be nice!

georgebrindeiro · August 3, 2022, 1:14am

I just confirmed that the example you shared works when installing via the CLI as well.

Did you include in your manifest.json the colossus-fire-event policy seen here?

rafael.camargo · August 3, 2022, 3:02pm

Uhum, @georgebrindeiro I was looking up to these configs as well. I uploaded the test here, this way will be easy to look up to the project.

The polices:

github.com

rafaelrcamargo/vtexio-event-examples/blob/main/manifest.json#L22


      
          "credentialType": "absolute",
          "policies": [
            {
              "name": "outbound-access",
              "attrs": {
                "host": "*",
                "path": "*"
              }
            },
            {
              "name": "colossus-fire-event"
            },
            {
              "name": "colossus-write-logs"
            },
            {
              "name": "ADMIN_DS"
            }
          ],
          "settingsSchema": {
            "title": "Event example",

Note that’s just a test, some random names and configs are just boilerplates

Saito · August 3, 2022, 9:32pm

@georgebrindeiro Just double checking … Does the “apps” sender include the VTEX IO CLI?

    "onAppInstalled": {
      "sender": "apps",
      "keys": ["setup"],
      "settingsType": "workspace"
    },

georgebrindeiro · August 3, 2022, 10:23pm

@rafael.camargo if I understood correctly, your full code is in the link you shared and it is still not working, right?

@Saito that’s what I was told, but let’s get to the end of the investigation to be 100% sure

rafael.camargo · August 4, 2022, 12:56pm

Exactly, this repo is just a “mock”, an example to test these events.

rafael.camargo · August 8, 2022, 7:40pm

Just pinging here, but in this meanwhile I re-wrote the example for a simpler approach, to be easy for to everyone install and test, and the repo stays the same. I’m willing we find a way to make them available!

Ps. The URL used in the client is a simple mock API from Postman where we can see the call that was made, feel free to change it during your tests.

velosov · October 24, 2023, 8:46pm

Folks, I noticed this is missing:

and might be the reason why it wasn’t working as expected:

Captura de Tela 2023-10-24 às 17.44.51

It’s worth trying