Orchestration SDKs

Exchanging custom JSON with DaVinci flows on the web

PingOne JavaScript

Firebase Analytics lets an application attach user properties to each user’s analytics profile. These properties drive audience segmentation: they define audiences for push messaging and remote configuration, and they slice analytics reports, for example comparing engagement between loyalty tiers or languages.

The attributes that make those segments meaningful, such as a loyalty tier or a language preference, originate in the user’s PingOne profile. Firebase Analytics does not know about them until the application sets them, and without using metadata exchange, the application developer would have to hard-code the rules that keep the two in step, in every app, and update them whenever the business changes.

With the Orchestration SDK Connector, the flow owns those rules. The flow reads the attributes from the PingOne profile, sends them to the application as JSON, and the application maps them to custom user properties in Firebase. The names of those properties are defined in advance in the Firebase console, so the attributes sent by the flow map onto custom definitions the application project already has. If the business adds a new segment, the flow changes and the application does not.

The example uses two profile attributes, each created as a custom property in Firebase:

  • preferred_language, set unconditionally, because the application needs it to function.

  • loyalty_tier, a personalization attribute used for segmentation, set only when the user has consented to analytics profiling.

The flow builder configures these attributes in the connector’s Custom Metadata (JSON) field, of the Exchange Custom Metadata with DaVinci SDK capability:

Example JSON payload configured in the connector
{
  "action": "setAnalyticsProperties",
  "properties": {
    "preferred_language": "{{local.mfauserlook1.payload.output.matchedUser.preferredLanguage}}",
    "loyalty_tier": "{{local.mfauserlook1.payload.output.matchedUser.loyaltyTier}}"
  }
}

Consent state lives on the device, so the flow cannot know whether the user has opted in.

This example use case assumes the application stores the user’s analytics consent decision locally, for example from a preferences screen.

The application consults this flag when deciding which properties to set, and reports any property it skipped in the result so the flow can react.

The flow cannot change the device’s stored flag directly.

Instead, it presents the consent form inside the flow itself, for example using a PingOne Form connector, so the user’s answer becomes a DaVinci variable.

The flow then routes back through the connector with a fresh payload that includes the answer, for example "consent_granted": true.

On this second pass, the application sets the previously skipped property, and can also save the decision to its local flag so it holds for future flows.

Returning a JSON response to DaVinci

Because setting a Firebase user property is a fire-and-forget call, the application cannot report the properties themselves back to the flow. Instead, it reports what it did:

  • On success, the application returns status and the list of properties it actually set:

    Example success result
    {
      "status": "success",
      "propertiesSet": ["preferred_language", "loyalty_tier"]
    }

    In a flow, a decision node can check the response to see whether loyalty_tier appears in the returned propertiesSet list.

    If it does, the flow continues. If it does not, the flow can present a consent form, for example using a PingOne Form connector, and route back through the Orchestration SDK Connector after the user opts in, so the application sets the missing property.

  • On failure, for example when the Firebase SDK is not initialized, the application sets a structured error and the flow follows the connector’s error branch:

    Example error result
    {
      "error": {
        "code": "FIREBASE_UNAVAILABLE",
        "message": "Firebase Analytics is not initialized"
      }
    }

Before you begin

To complete this use case you need:

  • A PingOne environment with DaVinci enabled.

  • A DaVinci flow that uses the Orchestration SDK Connector, with the Custom Metadata (JSON) field configured with the payload your application expects.

  • A client application that integrates the DaVinci module of the Orchestration SDK. Refer to Using the DaVinci module if you have not yet integrated it.

  • If you are following the Firebase Analytics example, a Firebase project with Google Analytics enabled, and the Firebase Analytics SDK added to your application.

  • If you are following the Firebase Analytics example, custom user property definitions created in the Firebase console under Analytics > Custom definitions, matching the profile attributes the flow sends. The application maps each attribute from the JSON payload onto the matching property definition by name.

Step 1. Handling the metadata collector

When a DaVinci flow reaches an Orchestration SDK Connector node, the flow response contains a MetadataCollector in the collectors returned by getCollectors().

The collector object exposes output.config, the JSON payload configured in the connector.

Find the MetadataCollector among the flow’s collectors and check the requested action
const collectors = davinciClient.getCollectors();

collectors.forEach((collector) => {
  if (collector.type === 'MetadataCollector') {
    switch (collector.output.config.action) {
      case 'setAnalyticsProperties':
        syncAnalyticsProperties(collector.output.config);
        break;
      // ...handle other metadata actions
      default:
        break;
    }
  }
});

Dispatch on the action element to decide what on-device work the flow has requested, and route the collector to the function that performs it. In this example, an action of setAnalyticsProperties calls syncAnalyticsProperties(), covered in Step 2.

The MetadataCollector is headless, so it needs no user interface.

Your application performs the on-device work and continues the flow without showing anything to the user.

Step 2. Reading the payload and performing the on-device work

Read the collector’s payload to determine what work the flow has asked for, then perform that work with any SDK or logic available in your application.

The following example follows the Firebase Analytics use case described earlier. For each entry in the properties object it performs the following steps:

  1. Consults the application’s stored consent flag, and skips any property the user has not consented to, in this example loyalty_tier.

  2. Maps the entry to a Firebase user property by calling the setUserProperty function.

    Learn more about custom properties in Set user properties in the Firebase documentation.

  3. Records the property name in the propertiesSet list.

The propertiesSet list is returned to the flow in the result, so the flow knows which user properties the application actually created:

Example function to map the payload to Firebase user properties
async function syncAnalyticsProperties(jsonPayload) {
  const properties = jsonPayload.properties ?? {};

  const propertiesSet = [];

  for (const [name, value] of Object.entries(properties)) {
    // Respect the app’s stored consent flag; skip profiling-related
    // properties the user has not consented to.
    if (name === 'loyalty_tier' && !consentManager.allowsAnalyticsProfiling) continue;

    // Add the property to Firebase analytics to segment activities
    setUserProperty(name, value);

    // Record the property so the result can report it back to the flow
    propertiesSet.push(name);
  }

  return { status: 'success', propertiesSet };
}

The example consults a consent flag only for the loyalty_tier property, because that property exists for segmentation.

Properties the application needs in order to function, such as preferred_language, are set unconditionally.

If your application does not gate properties on consent, every requested property appears in the result.

Step 3. Setting the result and continuing the flow

The Orchestration SDK provides an update() function on the collector, which sets the JSON result posted back to DaVinci when the flow resumes. Pass it an object for the success path, or a MetadataError object with code and message properties to route the flow through the connector’s error branch.

Create the contents of the response by calling update(), then continue the flow as usual.

If you call next() without calling update() first, the resume request is sent with an empty result.

What happens to the flow is then determined by DaVinci, not by the Orchestration SDK.

Set the result and continue the flow
const collectors = davinciClient.getCollectors();

for (const collector of collectors) {
  if (collector.type === 'MetadataCollector') {
    switch (collector.output.config.action) {
      case 'setAnalyticsProperties':
        try {
          const result = await syncAnalyticsProperties(collector.output.config);
          davinciClient.update(collector)(result);
        } catch (error) {
          davinciClient.update(collector)({
            code: 'FIREBASE_UNAVAILABLE',
            message: 'Firebase Analytics is not initialized',
          });
        }
        break;
      // ...handle other metadata actions
      default:
        break;
    }
  }
}

await davinciClient.next();

The flow resumes with your result exposed through the connector’s output schema, and the flow’s decision nodes can branch on values such as output.status and output.propertiesSet.

When the flow loops back through the connector, for example after the user grants consent in a form, the collector receives a fresh payload and your application repeats the same sequence.