Part 1: My first Surface

Create a Surface

To create your first Surface:

1. Navigate to the Surfaces page in the MonetizationOS console
2. Click "Add Surface"
3. Give it a name, e.g. "Hello, World!" Keep note of the slug generated (e.g. "hello-world") as you'll need this for API calls
4. Click "Create Surface"

Because we are using the Preview environment, all changes will automatically be deployed and reflected in API calls.

Make your first Surface decision

To make your first Surface decision use the following cURL command, making sure to replace $SURFACE_SLUG with your Surface slug (e.g. "hello-world") and $API_KEY with your API Secret key.

curl -X POST https://api.monetizationos.com/api/v1/surface-decisions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "anonymousIdentifier": "test"
  }
}'

You should receive a response similar to the following:

{
    "status": "success",
    "eventId": "941c5b52-39ff-4dab-9031-e39ef37e061a",
    "identity": {
        "authType": "anonymous",
        "identifier": "test",
        "isAuthenticated": false,
        "jwtClaims": {}
    },
    "customer": {
        "isCustomer": false,
        "hasProducts": false,
        "customerIdentifiers": []
    },
    "features": {},
    "surfaceBehavior": {}, // Note the empty behavior here
    "componentsSkipped": false,
    "componentBehaviors": {} // and here
}

Congratulations, you have made your first Surface decision! There are however no workflows being evaluated yet, so we can see in the response that there are no surface or component behaviors.

Hello, Surface Workflow!

Let's add a basic workflow to start making decisions on your Surface. We will create a surface workflow, these are workflows that apply to the entire surface. For example, you might want to block access to an entire web app or API.

How to add a Surface Workflow:

1. Return to your Surface in the MonetizationOS console
2. Click on the "Workflow" tab
3. Click "Add Workflow"

You should now see a code editor with a default workflow. Workflows are written in TypeScript, a superset of JavaScript. The code editor includes syntax highlighting, tooltips, and error checking to help you write valid code. Use Ctrl + space to see available completions.

Replace the default code with the following, and click "Update Workflow" to save your changes:

const workflow: SurfaceWorkflow = async () => {
    return {
        // Custom user-defined properties
        properties: {
            userMessage: "Hello, World!",
        },
    };
};

export default workflow;

What this workflow does is add a custom property to the surface decision response called userMessage with the value "Hello, World!". This is a simple example, but you can use workflows to implement complex logic based on user grants, request data, or any other data point.

Make your second Surface decision

Rerun the same cURL command as Step 2 to see the updated response with your workflow applied.

You should receive a response similar to the following:

{
    "status": "success",
    "eventId": "0c7a44d0-41db-4c95-b7fd-3b937b57a1da",
    "identity": {
        "authType": "anonymous",
        "identifier": "test",
        "isAuthenticated": false,
        "jwtClaims": {}
    },
    "customer": {
        "isCustomer": false,
        "hasProducts": false,
        "customerIdentifiers": []
    },
    "features": {},
    "surfaceBehavior": {
        "properties": {
            "userMessage": "Hello, World!"
        }
    },
    "componentsSkipped": false,
    "componentBehaviors": {}
}