How to get project id and token

Please contact us.

Usage

Install Footprint SDK

Footprint analytics SDK requires python 3.6 above and lower than python 4.

pip install footprint-analytics

Simple Demo

import time
import logging
from fga import FGA, User, Event, Account, Config


logger=logging.getLogger('fga')
logger.setLevel(logging.DEBUG)
ch = logging.StreamHandler()
ch.setLevel(logging.INFO)
logger.addHandler(ch)


client = FGA(
  token='xxxxxxxx',
  project_id=2,
  configuration=Config(logger=logger)
)

user = User(
    user_id='sdk_user_id_2',
    user_name='sdk_user_name_2',
    sign_up_at=int(time.time())
)

event = Event(
    event_type='login',
    event_name='login',
    user_id='sdk_user_id_2',
    event_id='sdk_event_id_2',
)
account = Account(
    user_id='sdk_user_id_2',
    wallet_address='0x1234567890'
)

if __name__ == '__main__':
    client.track(event)
    client.user_set(user)
    client.account_set(account)

Initialize SDK

You must initialize the SDK before any events are instrumented. The token for your Footprint project is required. You can also pass a config object in this call. You can use the SDK client instance across requests after it's initialized.

from fga import FGA

client = FGA(
  token=FOOTPRINT_PROJECT_TOKEN,
  project_id=1
)

Configuration

NameField TypeDescriptionRequirementDefault Value
tokenStringThe token of the Footprint project. Events sent by the client instance are in this project. Set when you initialize the client instance.RequiredNone
project_idIntegerThe id of the Footprint project.RequiredNone
flush_queue_sizeIntegerEvents wait in the buffer and are sent in a batch. The buffer is flushed when the number of events reaches flush_queue_size.Optional200
flush_interval_millisIntegerEvents wait in the buffer and are sent in a batch. The buffer is flushed every flush_interval_millis milliseconds.Optional1 seconds
flush_max_retriesIntegerThe number of times the client retries an event when the request returns an error.Optional12
callbackFunctionClient level callback function. Takes three parameters: 1. event: Event instance 2. code: integer of HTTP response code 3. message: a string message.OptionalNone
opt_outBooleanOpt out option. If set to True, client doesn't process and send events.OptionalFalse
from fga import FGA
from fga.config import Config 

def callback_func(event, code, message=None):
  # callback function that takes three input parameters
  # event: the event that triggered this callback
  # code: status code of request response
  # message: a optional string message for more detailed information

config = Config(
  flush_queue_size=10,
  fulush_interval_millis=1,
  flush_max_retries=1,
  callback=callback_func,
  opt_out=True
)

client = FGA(
  token=FOOTPRINT_PROJECT_TOKEN,
  project_id=1,
  configuration=config
)

Set User Properties

User properties help you understand your users at the time they performed some action within your app such as their device details, their preferences, or language.

Set user properties

The user object provides controls over setting user properties. An user object must first be instantiated, then user_set methods can be called on it, and finally the client makes a call with the user object.

from fga import FGA, User


client = FGA(
  token=FOOTPRINT_PROJECT_TOKEN,
  project_id=1
)

user = User(
    user_id="USER_ID",
    user_name="USER_NAME",
    sign_up_at=int(time.time())
)

client.user_set(user)

NameField TypeDescriptionRequirementDefault Value
user_idStringUnique user identifier.RequiredNone
user_nameStringThe original name from source data.RequiredNone
sign_up_atIntegerThe date of user sign up. Eg:1718296406.RequiredNone
user_propertiesDictYou can put all the other properties of the user in the user_properties field to customize the analytics, due to this field will be standardized to the extra_data field on the standard table user.OptionalNone
user_properties.sign_up_deviceStringThe device used for sign up. This field is automatically normalized to the table.OptionalNone
user_properties.acount_typeStringThe type of account. such as google, apple, email. This field is automatically normalized to the table.OptionalNone
user_properties.idfaStringIdentifier for Advertisers. This field is automatically normalized to the table.OptionalNone
user_properties.udidStringUniversal Device Identifier. This field is automatically normalized to the table.OptionalNone
user_properties.countryStringStandard ISO 3166-3. This field is automatically normalized to the table.OptionalNone
user_properties.emailStringThe email address of user. This field is automatically normalized to the table.OptionalNone
user_properties.ipStringThe ip address of user. This field is automatically normalized to the table.OptionalNone
user_properties.twitterStringThe twitter account of user. This field is automatically normalized to the table.OptionalNone
user_properties.discordStringThe discord account of user. This field is automatically normalized to the table.OptionalNone

Track User Event

Events represent how users interact with your application. For example, login may be an action you want to note.

Event Properties

NameField TypeDescriptionRequirementDefault Value
event_idStringUnique event identifier.RequiredNone
user_idStringUnique user identifier.RequiredNone
event_typeStringThe type of event. The standard events mainly include:install, sign_up, login, open_app,play_game,reward and these type will be showed on standard dashboard. You can custom event type, but no show on standard dashboard.RequiredNone
event_nameStringThe name of event.RequiredNone
event_propertiesDictYou can put all the other properties of the event in the event_properties field to customize the analytics, due to this field will be standardized to the extra_data field on the standard table user_event.OptionalNone
timeIntegerThe time of event occurs, Eg:1718296406.Optionaltime.time()
event_properties.device_idStringThe name is the original event from source data. This field is automatically normalized to the table.OptionalNone
event_properties.event_deviceStringThe device used for the event. Enum: website, android, ios. This field is automatically normalized to the table.OptionalNone
event_properties.event_sourceStringThe source of event. Enum: web2, web3Optionalweb2
from fga import FGA, Event


client = FGA(
  token=FOOTPRINT_PROJECT_TOKEN,
  project_id=1
)

# Track events with optional properties
client.track(
    Event(
        event_id="sdk_event_id_1",
        event_type="login",
        user_id="sdk_user_id_1",
        event_name="login"
    )
)

Set Account Mapping

Account mapping represent need to combine web3 data to analyze certain user behaviors, need a mapping relationship between wallet_address and user_id.

User Properties

NameField TypeDescriptionRequirementDefault Value
wallet_addressStringThe address of web3 account.RequiredNone
user_idStringUnique user identifier.RequiredNone
user_propertiesDictYou can put all the other properties of the event in the event_properties field to customize the analytics, due to this field will be standardized to the extra_data field on the standard table account_mapping.OptionalNone
user_properties.wallet_typeStringThe type of wallet. The standard wallet mainly include:EoA, MPC, AA, Non Custodial,Custodial. This field is automatically normalized to the table.OptionalEoA
user_properties.wallet_sourceStringThe source of wallet. The standard wallet mainly include:signup, public, giveaway. This field is automatically normalized to the table.Optionalsignup
user_properties.wallet_providerStringThe provider of wallet. The standard wallet mainly include:metamask, W3A, OKX, Halo. This field is automatically normalized to the table.Optionalmetamask
user_properties.login_methodStringThe method of account login. The standard wallet mainly include: google, twitter, discord, wallet-connect-v2, facebook, wallet-connect-v1. This field is automatically normalized to the table.OptionalNone
user_properties.chainStringBlockchain network, enum: Ethereum, BNB Chain, Polygon. This field is automatically normalized to the table.OptionalNone
user_properties.ecosystem_idStringIf you need to analyze the behavior of the same user in different projects, you need to populate this field. This field is automatically normalized to the table.OptionalNone
user_properties.wallet_linked_atDateThe time of web3 account be linked for web2 account. The format is %Y-%m-%d %H:%M:%S. This field is automatically normalized to the table.OptionalNone
from fga import FGA, Account


client = FGA(
  token=FOOTPRINT_PROJECT_TOKEN,
  project_id=1
)

account = Account(
    user_id='sdk_user_id_2',
    wallet_address='0x1234567890'
)

client.account_set(account)


View Data From SDK

Generally, after successful uploading, you will see the corresponding data within 1min.

You can login Footprint Growth Analytics page, and click Users -> Users Acquistion, the Number of Users of this dashboard can show the changes if you set user. See screenshot as follow:

Click the User Engagement menu. The DAU metric of this dashboard can show the changes if you track event. See screenshot as follow:

Custom Analysis

Entering Custom Analysis page, directly use the user and user_event table to do some custom analytics. And these standard tables have a field extra_data that stored the event_properties and user_properties from SDK.