Overview

The Sidecar SDK is used to interact with the Stigg Sidecar Service, which provides low latency entitlement checks, handles caching, and subscribes to real-time entitlement and usage data updates.

Learn more about the Stigg Sidecar service.

Installing the SDK

The first step is to install the Stigg SDK as a dependency in your application:

$ pip install stigg-sidecar-sdk

Retrieving the server API Key

In the Stigg app, go to Settings > Account > Environments.

Copy the Server API key of the relevant environment.

Initializing the SDK

Development

Import the Stigg SDK and initialize it with your environment API key:

from stigg_sidecar_sdk import Stigg, ApiConfig, LocalSidecarConfig

stigg = Stigg(
  ApiConfig(
    api_key="<SERVER_API_KEY>",
  ),
  # for development purposes, a sidecar will be spawned as a subprocess: 
  local_sidecar_config=LocalSidecarConfig(
    redis=RedisOptions(
      environment_prefix="development",
      host="localhost",
      port=6379,
      db=0
    )
  )
)

For testing & development purposes, Stigg will run the Sidecar service in a child process. The service listens for requests on address localhost:8433 by default.

For production, it is highly recommend to do run the Sidecar in a separate container, you can find more info in the Sidecar page.

Production

For production use, its recommended to deploy the Sidecar service using the sidecar pattern, or as a standalone service.

You set the remote sidecar host and port parameters as part of the SDK initialization:

from stigg_sidecar_sdk import Stigg, ApiConfig

stigg = Stigg(
  	# To access the API you need to set the server AP key
    ApiConfig(
	    api_key="<SERVER_API_KEY>",
    ),
    # For production use, set remote sidecar host and port:
    remote_sidecar_host='localhost',
    remote_sidecar_port=8443
)

Learn more about running the Sidecar service as separate container.

Getting the entitlement of a customer to a specific feature

Checking the entitlement of a boolean feature

from stigg_sidecar_sdk import GetBooleanEntitlementRequest

resp = await stigg.get_boolean_entitlement(GetBooleanEntitlementRequest(
  customer_id='customer-demo-01',
  feature_id='feature-03-custom-domain',
  resource_id='site-01' # Optional, specify the resource ID
))

if resp.has_access:   
  pass # Customer has access to the feature

{
  "hasAccess": true,
  "isFallback": false,
  "accessDeniedReason": null,
  "entitlement": {
    "feature": {
      "id": "feature-04-analytics",
      "featureType": "FEATURE_TYPE_BOOLEAN",
      "units": "",
      "unitsPlural": "",
      "meterType": "METER_TYPE_NONE",
      "isMetered": false
    }
  }
}

{
  "hasAccess": true,
  "isFallback": false,
  "accessDeniedReason": null,
  "entitlement": {
    "feature": {
      "id": "feature-03-custom-domain",
      "featureType": "FEATURE_TYPE_BOOLEAN",
      "units": "",
      "unitsPlural": "",
      "meterType": "METER_TYPE_NONE",
      "isMetered": false
    }
  }
}

Checking the entitlement of a numeric configuration feature

from stigg_sidecar_sdk import GetNumericEntitlementRequest

resp = await stigg.get_numeric_entitlement(GetNumericEntitlementRequest(
  customer_id='customer-demo-01',
  feature_id='feature-06-max-file-size',
  resource_id='site-01' # Optional, resource ID
))

if resp.has_access:   
  value = resp.entitlement.value # Entitlement value

{
  "hasAccess": true,
  "isFallback": false,
  "accessDeniedReason": null,
  "entitlement": {
    "feature": {
      "id": "feature-06-max-file-size",
      "featureType": "FEATURE_TYPE_NUMBER",
      "units": "MB",
      "unitsPlural": "MB",
      "meterType": "METER_TYPE_NONE",
      "isMetered": false
    },
    "value": 100,
    "isUnlimited": false
  }
}

{
  "hasAccess": false,
  "isFallback": false,
  "accessDeniedReason": "ACCESS_DENIED_REASON_NO_FEATURE_ENTITLEMENT_IN_SUBSCRIPTION",
  "entitlement": {
    "feature": null,
    "value": null,
    "isUnlimited": false
  }
}

Checking if a customer has access to a metered feature

from stigg_sidecar_sdk import GetMeteredEntitlementRequest

resp = await stigg.get_metered_entitlement(GetMeteredEntitlementRequest(
  customer_id='customer-demo-01',
  feature_id='feature-01-templates',
  resource_id='site-01', # Optional, resource ID
))	

if resp.has_access:   
  pass # Has access, current usage is under the entitlement limit

{
  "hasAccess": true,
  "isFallback": false,
  "accessDeniedReason": null,
  "requestedUsage": 0.0,
  "entitlement": {
    "feature": {
      "id": "feature-01-templates",
      "featureType": "FEATURE_TYPE_NUMBER",
      "units": "template",
      "unitsPlural": "templates",
      "meterType": "METER_TYPE_FLUCTUATING",
      "isMetered": true
    },
    "usageLimit": 6.0,
    "isUnlimited": false,
    "currentUsage": 3.0,
    "resetPeriod": "ENTITLEMENT_RESET_PERIOD_UNSPECIFIED",
    "usagePeriodAnchor": null,
    "usagePeriodStart": null,
    "usagePeriodEnd": null
  }
}

{
  "hasAccess": false,
  "isFallback": false,
  "accessDeniedReason": "ACCESS_DENIED_REASON_NO_FEATURE_ENTITLEMENT_IN_SUBSCRIPTION",
  "requestedUsage": 1.0,
  "entitlement": {
    "feature": null,
    "usageLimit": null,
    "isUnlimited": false,
    "currentUsage": 0.0,
    "resetPeriod": "ENTITLEMENT_RESET_PERIOD_UNSPECIFIED",
    "usagePeriodAnchor": null,
    "usagePeriodStart": null,
    "usagePeriodEnd": null
  }
}

Proactively checking if a customer will have access to X units of a metered feature

resp = await stigg.get_metered_entitlement(GetMeteredEntitlementRequest(
  customer_id='customer-demo-01',
  feature_id='feature-01-templates',
  resource_id='site-01', # Optional, resource ID
  options=MeteredEntitlementOptions(requested_usage=10)
))

if resp.has_access:   
  pass # Has access, (current + requested usage) is under the entitlement limit

{
  "hasAccess": true,
  "isFallback": false,
  "accessDeniedReason": null,
  "requestedUsage": 1.0,
  "entitlement": {
    "feature": {
      "id": "feature-01-templates",
      "featureType": "FEATURE_TYPE_NUMBER",
      "units": "template",
      "unitsPlural": "templates",
      "meterType": "METER_TYPE_FLUCTUATING",
      "isMetered": true
    },
    "usageLimit": 6.0,
    "isUnlimited": false,
    "currentUsage": 3.0,
    "resetPeriod": "ENTITLEMENT_RESET_PERIOD_UNSPECIFIED",
    "usagePeriodAnchor": null,
    "usagePeriodStart": null,
    "usagePeriodEnd": null
  }
}

{
  "hasAccess": false,
  "isFallback": false,
  "accessDeniedReason": "ACCESS_DENIED_REASON_REQUESTED_USAGE_EXCEEDING_LIMIT",
  "requestedUsage": 10.0,
  "entitlement": {
    "feature": {
      "id": "feature-01-templates",
      "featureType": "FEATURE_TYPE_NUMBER",
      "units": "template",
      "unitsPlural": "templates",
      "meterType": "METER_TYPE_FLUCTUATING",
      "isMetered": true
    },
    "usageLimit": 6.0,
    "isUnlimited": false,
    "currentUsage": 3.0,
    "resetPeriod": "ENTITLEMENT_RESET_PERIOD_UNSPECIFIED",
    "usagePeriodAnchor": null,
    "usagePeriodStart": null,
    "usagePeriodEnd": null
  }
}

Getting all of the entitlements for a specific customer

from stigg_sidecar_sdk import GetEntitlementsRequest

resp = await stigg.get_entitlements(GetEntitlementsRequest(
  customer_id='customer-demo-01',
  resource_id='site-01' # Optional, resource ID
))

# All the entitlements the customer is entitled to  
entitlements = resp.entitlements

{
  "entitlements": [
    {
      "metered": {
        "feature": {
          "id": "feature-07-active-users",
          "featureType": "FEATURE_TYPE_NUMBER",
          "units": "active user",
          "unitsPlural": "active users",
          "meterType": "METER_TYPE_INCREMENTAL",
          "isMetered": true
        },
        "usageLimit": 25000.0,
        "currentUsage": 1.0,
        "resetPeriod": "ENTITLEMENT_RESET_PERIOD_MONTH",
        "usagePeriodAnchor": "2023-07-21T00:00:00Z",
        "usagePeriodStart": "2023-11-21T00:00:00Z",
        "usagePeriodEnd": "2023-12-21T00:00:00Z",
      }
    },
    {
      "boolean": {
        "feature": {
          "id": "feature-04-analytics",
          "featureType": "FEATURE_TYPE_BOOLEAN",
          "units": "",
          "unitsPlural": "",
          "meterType": "METER_TYPE_NONE"
        }
      }
    },
    {
      "numeric": {
        "feature": {
          "id": "feature-06-max-file-size",
          "featureType": "FEATURE_TYPE_NUMBER",
          "units": "MB",
          "unitsPlural": "MB",
          "meterType": "METER_TYPE_NONE"
        },
        "value": 100
      }
    },
    {
      "metered": {
        "feature": {
          "id": "feature-02-campaigns",
          "featureType": "FEATURE_TYPE_NUMBER",
          "units": "campaign",
          "unitsPlural": "campaigns",
          "meterType": "METER_TYPE_INCREMENTAL",
          "isMetered": true
        },
        "usageLimit": 32.0,
        "resetPeriod": "ENTITLEMENT_RESET_PERIOD_MONTH",
        "usagePeriodAnchor": "2023-02-21T00:00:00Z",
        "usagePeriodStart": "2023-11-21T00:00:00Z",
        "usagePeriodEnd": "2023-12-21T00:00:00Z"
      }
    },
    {
      "metered": {
        "feature": {
          "id": "feature-01-templates",
          "featureType": "FEATURE_TYPE_NUMBER",
          "units": "template",
          "unitsPlural": "templates",
          "meterType": "METER_TYPE_FLUCTUATING",
          "isMetered": true
        },
        "usageLimit": 6.0,
        "currentUsage": 3.0,
        "resetPeriod": "ENTITLEMENT_RESET_PERIOD_UNSPECIFIED"
      }
    },
    {
      "boolean": {
        "feature": {
          "id": "feature-03-custom-domain",
          "featureType": "FEATURE_TYPE_BOOLEAN",
          "units": "",
          "unitsPlural": "",
          "meterType": "METER_TYPE_NONE"
        }
      }
    }
  ]
}

Reporting usage measurements to Stigg

The Stigg SDK allows you to report usage measurements for metered features. The reported usage will be used to track, limit and bill the customer’s usage of metered features.

Stigg supports metering of usage from the following data sources:

Calculated usage - usage that has been aggregated and calculated by your application. This type is useful for features, such as: seats.
Raw events - raw events from your application, which Stigg filters and aggregates aggregate to calculate customer usage. This type is useful for features, such as: monthly active users (MAUs).

More details about Stigg’s metering and aggregation capabilities can be found here:

Stigg's metering and aggregation capabilities

Reporting of measurements to Stigg should be done only after the relevant resources have been provisioned in your application.
To ensure that the provisioned resources are aligned with the measurements that are reported to Stigg, ensure that customers are not allowed to allocate new resources until an acknowledgement about the processed measurement is received from the Stigg backend.

Validating that a measurement was successfully reported to Stigg is also possible in the customer details section of the relevant customer in the Stigg app.

Calculated usage

from stigg_sidecar_sdk import ReportUsageRequest

# Example: incrementing usage of a metered feature by 2

await stigg.report_usage(ReportUsageRequest(
  customer_id='customer-demo-01',
  feature_id='feature-01-templates',
  value=2,  # Usage amount
  resource_id='site-01' # Optional, resource ID
))

By default, the value reported should represent the change in usage of the feature, for example user added 2 more seats then the report usage call should have the value of 2.

In some cases, it’s more useful to set the usage to some value instead of reporting the change value, it’s possible by passing the updateBehavior parameter:

# Example: set usage of a metered feature to 3

resp = await stigg.report_usage(ReportUsageRequest(
  customer_id='customer-demo-01',
  feature_id='feature-01-templates',
  value=3,  # Usage amount
  update_behavior=UsageUpdateBehavior.USAGE_UPDATE_BEHAVIOR_SET,
  resource_id='site-01' # optional, resource ID
))

Raw events

from stigg_sidecar_sdk import ReportEventsRequest, EventDimensionValue

# Example: report user_login events

resp = await stigg.report_events(ReportEventsRequest(
  events=[Event(
    customer_id="customer-demo-01",
    resource_id='site-01', # Optional, resource ID
    event_name="user_login",
    idempotency_key="227c1b73-883a-457b-b715-6ba5a2c69ce4",
    dimensions={
      'user_id': EventDimensionValue(string_value='user-01'),
      'user_email': EventDimensionValue(string_value='john@example.com'),
    },
    timestamp=datetime.datetime.now(),  # Optional, pass it to report event with specific timestamp
  )]
))

It’s also possible to send a batch of events in one invocation.

The dimensions field support key value pairs, while keys are strictly of type string values can be string | number | boolean

Access to additional Stigg APIs

The Sidecar SDK exposes a type-safe generated API client that can be used for send requests to the Stigg API:

from stigg.generated import ProvisionCustomerInput, ProvisionSubscriptionInput, BillingPeriod

# Example: access the client through the `.api` field

cust_resp = await stigg.api.provision_customer(ProvisionCustomerInput(
  customer_id='customer-demo-01',
  email='john@example.com'
))

sub_resp = await stigg.api.provision_subscription(ProvisionSubscriptionInput(
  customer_id='customer-demo-01',
  plan_id='plan-revvenu-essentials',
  billing_period=BillingPeriod.MONTHLY
))

print(sub_resp.provision_subscription.status)  # SUCCESS

You can find all the available API client functions under each SDK language:

Python

Ruby

Java

Persistent caching

In order for the cache to survive between restarts or to be shared across multiple instances of the Sidecar service, you can configure the Sidecar to use Redis as a cache provider.

Prerequisites

Run a Persistent Cache Service in a separate process.

SDK configuration


from stigg_sidecar_sdk import Stigg, ApiConfig, LocalSidecarConfig, RedisOptions

stigg = Stigg(
  ApiConfig(
    api_key="<SERVER_API_KEY>",
  ),
  # For development purposes, configure local sidecar to use redis: 
  local_sidecar_config=LocalSidecarConfig(
    redis=RedisOptions(
      environment_prefix="development",
      host="localhost",
      port=6379,
      db=0
    )
  ),
  # For production use, provide remote sidecar with the REDIS_* env vars:
  remote_sidecar_host='localhost',
  remote_sidecar_port=8443
)

Codebase integration

API and SDK references

Changelog

Sidecar

Overview

Installing the SDK

Retrieving the server API Key

Initializing the SDK

Development

Production

Getting the entitlement of a customer to a specific feature

Checking the entitlement of a boolean feature

Checking the entitlement of a numeric configuration feature

Checking if a customer has access to a metered feature

Proactively checking if a customer will have access to X units of a metered feature

Getting all of the entitlements for a specific customer

Reporting usage measurements to Stigg

Stigg's metering and aggregation capabilities

Calculated usage

Raw events

Access to additional Stigg APIs

Persistent caching

Prerequisites

SDK configuration

SDK changelog

Sidecar SDK changelog

Codebase integration

API and SDK references

Changelog

​Overview

​Installing the SDK

​Retrieving the server API Key

​Initializing the SDK

​Development

​Production

​Getting the entitlement of a customer to a specific feature

​Checking the entitlement of a boolean feature

​Checking the entitlement of a numeric configuration feature

​Checking if a customer has access to a metered feature

​Proactively checking if a customer will have access to X units of a metered feature

​Getting all of the entitlements for a specific customer

​Reporting usage measurements to Stigg

Stigg's metering and aggregation capabilities

​Calculated usage

​Raw events

​Access to additional Stigg APIs

​Persistent caching

​Prerequisites

​SDK configuration

​SDK changelog

Sidecar SDK changelog

Overview

Installing the SDK

Retrieving the server API Key

Initializing the SDK

Development

Production

Getting the entitlement of a customer to a specific feature

Checking the entitlement of a boolean feature

Checking the entitlement of a numeric configuration feature

Checking if a customer has access to a metered feature

Proactively checking if a customer will have access to X units of a metered feature

Getting all of the entitlements for a specific customer

Reporting usage measurements to Stigg

Calculated usage

Raw events

Access to additional Stigg APIs

Persistent caching

Prerequisites

SDK configuration

SDK changelog