Create the projects your SDKs report into, manage the keys that identify them, and control what happens to the data they collect.
What a project is
A project is one analytics world. Everything an SDK sends arrives stamped with a project, and every number Countly shows you is counted inside one. Two projects never share sessions, events, user profiles, funnels, dashboards or permissions, so the question "should this be its own project?" is really the question "should these numbers ever be added together?"
The usual shape is one project per product, not one per platform. An iOS app, its Android twin and the website in front of them belong in the same project when they are the same product to the people using them, because a single person moving between them should count once. Split them only when the audiences genuinely differ, or when the teams reading the numbers do.
A project carries a small amount of identity of its own. Its name and icon are what everyone else on the dashboard sees in the top bar. Its category is a label, nothing more. Its timezone is consequential, because it decides where one day ends and the next begins for every chart in the product. A project created in the wrong timezone reports correct data on the wrong days.
Below that identity sit the keys. A project has one current app key and, after a rotation, any number of older keys that are still accepted. The keys are how incoming data finds its way to this project rather than another one.
Projects are managed from one page, under Manage. Creating and deleting them is a global admin's job. Editing one is open to that project's admins.
Keys identify the sender
The app key is the only thing that connects an SDK to a project. It travels with every request the SDK makes, and the server uses it to decide which project the data belongs to. There is no second identifier and no fallback, so a wrong key is not an error the reader sees. It is data landing in someone else's project, or being refused.
Keys are unique across the whole server, and the check is wider than it looks. A key you type has to be free of every project's current key and also of every older key any project still accepts. That is why a key you rotated away from is not reusable somewhere else until you retire it, and why the create form pre-generates one for you.
A key is not a secret in the way a password is. It ships inside a mobile binary and it sits in the JavaScript of a web page, so anyone determined enough can read it. It identifies a sender, it does not authenticate one. What it protects against is accident, not intent.
When you do need to know that data came from your own client and not from someone replaying requests, that is the checksum salt. Set a salt on the project and configure the same value in the SDK, and the server will only accept requests signed with it. Leave it empty and no signature is required. The salt is the real secret of the pair, which is why the dashboard keeps it masked until you ask to see it.
A project can accept more than one key at a time, and that is the entire mechanism behind rotation. Countly never has to stop trusting the key your released app is already using in order to start trusting a new one.
Use Cases
Create a project for a new app
Start a new project when the data it collects should never be added to anything you already measure. A second app, a separate brand, a staging environment you want to keep out of the real numbers: each of those is its own project.
Open Projects under Manage and choose New project. Only the name and the app key are required, and the key is already filled in for you. Give the project the name the rest of the team will recognize in the top bar, because that is where they will meet it.
Set the timezone deliberately. It decides where each day starts for every chart in the product, and changing it later does not re-bucket data that has already been counted.
Once the project is created it becomes your active project straight away, so you can hand the key to whoever is doing the integration and watch the first data arrive on the SDK keys card. Until data arrives, the key's last received column reads "No data received yet", which is the fastest way to tell an integration problem from a quiet audience.
Rotate an app key without losing users
Rotate a key when it has spread somewhere it should not be, or when a release cycle is a good moment to move to a fresh one. Rotation is deliberately gentle, so there is rarely a reason to postpone it.
Open the project, find the SDK keys card and choose Regenerate. Countly proposes a new key, which you can accept or replace with one of your own. Confirming makes it the current key, the one every new integration should use.
The old key does not stop working. It moves down into the accepted list and keeps taking data from every client already deployed with it, which means nothing breaks on the phones you cannot update. User profiles are preserved as well: a project's user identities stay derived from the key that was in use before the first rotation, so the same person is still the same person afterwards.
Watch the old key's last received column over the following weeks. When it stops moving, the clients using it are gone, and you can retire it from the same card. Retiring is the only step that breaks anything, and it only breaks clients that are still sending on that key.
Clear data you no longer need
Clearing removes collected analytics data from a project while leaving the project itself in place. Reach for it when a retention policy says data past a certain age has to go, when a test flooded a project with data that was never real, or when you want a project back to an empty state without recreating it.
The danger menu at the right end of the project header holds Clear data, with the choice of everything older than one month, three months, six months, one year or two years, and a separate option for all data. The age options are the ones to prefer, because they leave the recent picture intact.
What survives a clear is what you have configured rather than collected. Event definitions stay, so the events you have named and set up keep their settings and start filling again. Project settings, keys and members are untouched.
Clearing cannot be undone, and it is a global admin's action. A locked project refuses it, which is the main reason to lock the projects that matter.
Lock a project against changes
Lock the projects where an accidental change would be expensive. Production, in other words, and anything else whose data a team depends on.
The lock is a switch in the project header, visible to global admins. Turning it on marks the project with a Locked pill everywhere it appears, and closes off the three things that cannot be taken back: clearing data, resetting the project, and deleting it. Editing project information is closed off as well, with the Edit button disabled and the reason on hover.
Nothing about collection changes. A locked project keeps receiving data from its SDKs exactly as before, and everyone keeps reading its reports.
Unlocking is a single switch away, which is the point. The lock is not a permission model, it is a deliberate pause between someone reaching for the danger menu and something irreversible happening.
Check who has access to a project
Before you hand a key to a team, or after someone leaves, it is worth knowing who can see a project's data. The Details card at the bottom of the page answers that.
It lists three groups. Global admins can do anything on any project, including the destructive actions. Admins can edit this project's information and manage its keys. Users can read its data and nothing more. The first few faces of each group are shown, with a count for the rest.
The same card carries the project's lifecycle: who created it, when it was created, when it was last edited, and when data last arrived. The last of those excludes the Data Populator, so a project that only ever received demo data still reads as having received nothing real.
If the card shows a notice instead of the roster, you are not an admin of that project. The roster and the dates are visible to project admins only, and the rest of the page carries on working.
FAQs
Should an iOS app and its Android version be one project or two?
One, in almost every case. They are the same product to the people using them, and a person who switches devices should count once rather than twice. Split them only when the audiences or the teams reading the numbers genuinely differ.
I rotated the key. Do I have to update my apps right away?
No. The old key stays accepted until you retire it, so deployed clients keep sending data with nothing to change. Move new integrations to the current key and retire the old one once its last received date stops moving.
Will rotating the key reset my user counts?
No. User identities stay derived from the key the project started with, so returning users are still recognized as the same profiles after any number of rotations.
Why can I not edit this project?
Either it is locked, or you are not one of its admins. Hover the disabled Edit button and it says which.
Where did the lock switch and the danger menu go?
They render for global admins only. A project admin can edit the project and manage its keys but cannot lock, clear, reset or delete it.
What is the checksum salt actually for?
It makes the server require a signature on incoming requests. Set the same value in the SDK and requests signed with it are accepted while unsigned ones are refused. Leaving it empty means no signature is required.
Does clearing data remove my events?
Clearing keeps event definitions and removes what was collected. Reset is the one that removes the definitions too.
The SDK keys card says no data received yet. Is the integration broken?
It means nothing has ever arrived on that key. If the project is new, check the key in the client matches the current one here. If the key is an old one you rotated away from, it is the expected reading.