Skip to main content

This is the official Python SDK for journy.io.

Project description

journy.io

journy.io Python SDK

pypi pypi downloads Code style: black

This is the official Python SDK for journy.io.

💾 Installation

You can use the python package manager (pip) to install the SDK:

pip install journyio-sdk

🔌 Getting started

Import

To start, first import the client.

from journyio.client import Client, Config

Configuration

To be able to use the journy.io SDK you need to generate an API key. If you don't have one you can create one in journy.io.

If you don't have an account yet, you can create one in journy.io or request a demo first.

Go to your settings, under the Connections-tab, to create and edit API keys. Make sure to give the correct permissions to the API Key.

from journyio.httpclient import HttpClientRequests

config = Config("api-key-secret")
http_client = HttpClientRequests()  # If wanted, an own implementation of the HttpClient interface can be created
client = Client(http_client, config)

Methods

Get API key details

from journyio.results import Success

result = client.get_api_key_details()
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # ApiKeyDetails
    print(result.permissions)  # list of strings denoting the permissions

Create or update user

💡 A user ID should be a robust, static, unique identifier that you recognize a user by in your own systems. Because these IDs are consistent across a customer’s lifetime, you should include a user ID in identify calls as often as you can. Ideally, the user ID should be a database ID.

💡 journy.io does not recommend using simple email addresses or usernames as user ID, as these can change over time. journy.io recommends that you use static IDs instead, so the IDs never change. When you use a static ID, you can still recognize the user in your analytics tools, even if the user changes their email address.

💡 The properties full_name, first_name, last_name, phone and registered_at will be used for creating contacts in destinations like Intercom, HubSpot, Salesforce, ...

from journyio.client import Properties
from journyio.user_identified import UserIdentified
from datetime import datetime

user = UserIdentified("userId", "name@domain.tld")
# or
user = UserIdentified.by_user_id("userId")
# or
user = UserIdentified.by_email("name@domain.tld")

properties = Properties()
properties["full_name"] = "John Doe"
properties["first_name"] = "John"
properties["last_name"] = "Doe"
properties["phone"] = "123"
properties["is_admin"] = True
properties["registered_at"] = datetime.now()
properties["age"] = 26
properties["array_of_values"] = ["value1", "value2"]
properties["key_with_empty_value"] = ""
properties["this_property_will_be_deleted"] = None

result = client.upsert_user(user, properties)
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Delete user

from journyio.client import Properties
from journyio.user_identified import UserIdentified
from datetime import datetime

user = UserIdentified("userId", "name@domain.tld")
# or
user = UserIdentified.by_user_id("userId")
# or
user = UserIdentified.by_email("name@domain.tld")

result = client.delete_user(user)
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Create or update account

💡 An account ID should be a robust, static, unique identifier that you recognize an account by in your own systems. Ideally, the account ID should be a database ID.

💡 The properties name, mrr, plan and registered_at will be used to create companies in destinations like Intercom, HubSpot, Salesforce, ...

from journyio.account_identified import AccountIdentified
from journyio.user_identified import UserIdentified
from datetime import datetime

account = AccountIdentified("accountId", "www.domain.tld")
# or
account = AccountIdentified.by_account_id("accountId")
# or
account = AccountIdentified.by_domain("www.domain.tld")

properties = Properties()
properties["name"] = "ACME, Inc"
properties["mrr"] = 399
properties["plan"] = "Pro"
properties["registered_at"] = datetime.now()
properties["is_paying"] = True
properties["array_of_values"] = ["value1", "value2"]
properties["key_with_empty_value"] = ""
properties["this_property_will_be_deleted"] = None

result = client.upsert_account(account, properties)
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Delete account

from journyio.account_identified import AccountIdentified
from journyio.user_identified import UserIdentified
from datetime import datetime

account = AccountIdentified("accountId", "www.domain.tld")
# or
account = AccountIdentified.by_account_id("accountId")
# or
account = AccountIdentified.by_domain("www.domain.tld")

result = client.delete_account(account)
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Add user(s) to an account

from journyio.account_identified import AccountIdentified
from journyio.user_identified import UserIdentified

account = AccountIdentified.by_account_id("accountId")

user1 = UserIdentified.by_user_id("memberId1")
user2 = UserIdentified.by_email("member2@domain.tld")

result = client.add_users_to_account(account, [user1, user2])
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Remove user(s) from an account

When removing a user, the user will still be stored in journy.io, but marked as "removed".

from journyio.account_identified import AccountIdentified
from journyio.user_identified import UserIdentified

account = AccountIdentified.by_domain("www.domain.tld")

user1 = UserIdentified.by_user_id("memberId1")
user2 = UserIdentified.by_email("member2@domain.tld")

result = client.remove_users_from_account(account, [user1, user2])
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Link web visitor to an app user

You can link a web visitor to a user in your application when you have our snippet installed on your website. The snippet sets a cookie named __journey. If the cookie exists, you can link the web visitor to the user that is currently logged in:

from journyio.user_identified import UserIdentified

user = UserIdentified("userId", "name@domain.tld")
# or
user = UserIdentified.by_user_id("userId")
# or
user = UserIdentified.by_email("name@domain.tld")

result = client.link(user, "deviceId")
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

To get the cookies (for the deviceId) you can use:

Flask

@app.route('/...')
def method():
    device_id = request.cookies.get('__journey')
    if device_id:
        ...
    ...

Django

def method(request):
    device_id = request.COOKIES.get('__journey')
    if device_id:
        ...
    ...

Add event

from datetime import datetime
from journyio.events import Event, Metadata
from journyio.account_identified import AccountIdentified
from journyio.user_identified import UserIdentified

account = AccountIdentified("accountId", "www.domain.tld")
user = UserIdentified("userId", "name@domain.tld")

metadata = Metadata()
metadata["metadata1"] = "value1"
event = Event()
    .for_user_in_account("settings_updated", user, account)
    .happened_at(datetime.now())
    .with_metadata(metadata)
result = client.add_event(event)
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # None

Get tracking snippet for a domain

from journyio.results import Success

result = client.get_tracking_snippet("www.journy.io")
if isinstance(result, Success):
    print(result.request_id)  # str
    print(result.calls_remaining)  # int
    print(result.data)  # TrackingSnippetResonse
    print(result.domain)  # str
    print(result.snippet)  # str

Handling errors

Every call will return a Success or Failure object. Success objects refer to the call having succeeded (and optionally containing data). A Failure object refers to the API returning an error. This can be any APIError (too many requests, not found...). Our SDK only throws JournyExceptions, no other exceptions should be called. JournyExceptions are provided with useful messages, which state where the error was made.

from journyio.utils import JournyException

try:
    result = client.get_tracking_snippet("www.journy.io")
    if isinstance(result, Success):
        print(result.request_id)  # str
        print(result.calls_remaining)  # int
        print(result.data)  # TrackingSnippetResonse
    else:
        print(result.request_id)  # str
        print(result.calls_remaining)  # int
        print(result.error)  # APIError
except JournyException as e:
    print(e.msg)  # str with error message

The request ID can be useful when viewing API logs in journy.io.

📬 API Docs

API reference

💯 Tests

To run the tests:

cd tests
pip install -r requirements.txt
pip install -U pytest
python scripts/createversion.py 0.0.0
pytest

❓ Help

We welcome your feedback, ideas and suggestions. We really want to make your life easier, so if we’re falling short or should be doing something different, we want to hear about it.

Please create an issue or contact us via the chat on our website.

🔒 Security

If you discover any security related issues, please email security at journy io instead of using the issue tracker.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

journyio-sdk-2.3.1.tar.gz (16.4 kB view details)

Uploaded Source

Built Distribution

journyio_sdk-2.3.1-py3-none-any.whl (18.6 kB view details)

Uploaded Python 3

File details

Details for the file journyio-sdk-2.3.1.tar.gz.

File metadata

  • Download URL: journyio-sdk-2.3.1.tar.gz
  • Upload date:
  • Size: 16.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.3 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10

File hashes

Hashes for journyio-sdk-2.3.1.tar.gz
Algorithm Hash digest
SHA256 0e1556cfd52127c2f8876e6f99382b2355bf4acd68ef939baaad726e92a20e9f
MD5 ed9a45058089d6c79bec92b013ea7df8
BLAKE2b-256 3900669aa6a13a12d69e70e98a2d06fdbb59203256240aa69d1e8b68e063b3e5

See more details on using hashes here.

File details

Details for the file journyio_sdk-2.3.1-py3-none-any.whl.

File metadata

  • Download URL: journyio_sdk-2.3.1-py3-none-any.whl
  • Upload date:
  • Size: 18.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.3 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10

File hashes

Hashes for journyio_sdk-2.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 43c8bd80b4d8d254316304496bf040636f7b456bf6ccf1eb533d003a1031874b
MD5 50608d94a6219a7d0b0f53238a8a2229
BLAKE2b-256 081a032b78dd251f4233b7dbcefe10844a351e142383e93a7a78049748115256

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page