Package: pyramid-mixpanel
Integrate yourPyramidapp withMixpanelto learn who your users are and how they are using your app.Opinionated Mixpanel (and Customer.io) integrationThe reason this package exists is to provide sane defaults when integrating with Mixpanel. Instead of chasing down event name typos and debugging why tracking does not work, you can focus on learning what is important to your users.Younever have typo-duplicated eventsin Mixpanel, because every event name comes from a dataclass, never from a string that can be miss-typed by mistake.Same for properties. Like events,properties are hardcodedas dataclasses.All"special" and "reserved" events and properties are already provided, no need to chase them down in various Mixpanel docs.Yourapp never stops working if Mixpanel is down, but you still get errors in your logs so you know what is going on.Younever forget to callflush()on the events buffer, sincepyramid_mixpanelhooks into the request life-cycle and callsflush()at the end of the request processing.Youdefer sending events until the entire request is processed successfully, i.e. never send events like "User added a thing" if adding the thing to DB failed at a later stage in the request life-cycle.NOTE: At the end of 2021, Mixpanel issunsetting their Email Messagesfeature. Since we rely heavily on those atNiteo, we are addingCustomer.iointegration into this library, to replace Mixpanel's Email Messages. If you don't want to use Customer.io, nothing changes for you, just keep usingpyramid_mixpanelas always. If you do want to use Customer.io, then
install this package aspyramid_mixpanel[customerio]and add the following registry settings. Then allprofile_setandtrackcalls will get automatically replicated to Customer.io. Other calls such asprofile_appendwill only send to Mixpanel.customerio.tracking.site_id:<secret>customerio.tracking.api_key:<secret>customerio.tracking.region:<eu OR us>If you want to skip sending sometrackorprofile_setcalls to Customer.io, add theskip_customerio=Trueas a function parameter.FeaturesBuilds on top ofhttps://mixpanel.github.io/mixpanel-python/.Provides a handyrequest.mixpanel.*helper for sending events and setting profile properties.Makes sure to call.flush()at the end of request life-cycle.Provides dataclasses for events and properties, to avoid typos.You can roll your ownConsumer, for example one that schedules a background task to send events, to increase request processing speed, since HTTP requests to Mixpanel are offloaded to a background task.Provides a MixpanelQuery helper to useJQLto query Mixpanel for data. Some common queries like one for getting profiles by email are included.In local development and unit testing, all messages are stored as plain dicts inrequest.mixpanel.mocked_messages. This makes writing integration tests a breeze. By default, these dicts omit "library" properties such astoken,time,mp_liband similar, to make tests less verbose. If you need them, setMockedConsumer.DROP_SYSTEM_MESSAGE_PROPERTIEStoTrue.Automatically sets Mixpanel trackingdistinct_idifrequest.userexists. Otherwise, you need to set it manually withrequest.mixpanel.distinct_id = 'foo'.Getting startedDeclarepyramid_mixpanelas a dependency in your Pyramid project.Include the following lines:config.include("pyramid_mixpanel")Tell mixpanel_mixpanel how you want to use it:# for local development and unit testing# events will be stored in request.mixpanel.mocked_messagesmixpanel.token=false# minimal configurationmixpanel.token=<TOKEN># enable support for querying Mixpanel datamixpanel.api_secret=<SECRET># custom events and propertiesmixpanel.events=myapp.mixpanel.Eventsmixpanel.event_properties=myapp.mixpanel.EventPropertiesmixpanel.profile_properties=myapp.mixpanel.ProfileProperties# defer sending of Mixpanel messages to a background task queuemixpanel.consumer=myapp.mixpanel.QueuedConsumer# enable logging with structlogpyramid_heroku.structlog=trueFor view code dealing with requests, a pre-configuredrequest.mixpanelis available.Design defenseThe authors ofpyramid_openapi3believe that while Mixpanel allows sending schema-less data, that can change as requirements for the project change, it is better to be precise about what "events" you send and what the properties of those events will be called. Same for "profiles". Here are the reasons that accumulated over 5 years of using Mixpanel atNiteo:a) There will be typos in event and property names. They will clutter your Mixpanel dashboard and slow you down.b) There will be differently named events for similar actions sent from different parts of your codebase. Then in your Mixpanel dashboard you'll haveUser Clicked ButtonandButton Clickedevents in you won't be sure which to use, and what's the difference between them.c) Your events and properties will not be consistently named, because they will be sent from different parts of your codebase, by different authors. Your Mixpanel dashboard will feel somewhat "broken" because some events will be in past tense (User Logged In), some in all lowers caps (generated invoice), some with only the action verb (click) and so on.All issues outlined above are alleviated using this package because all event & property names are defined as dataclasses, in asingle source of truthmanner. No typos are possible once the initial specification is done. You immediately recognize bad naming patterns because all event & property names are in a single file.Naming best practiceIn order to have nice and consistent event and property names, the authors of this package suggest using the following guidelines when coming up with names:Use the<item> <action>format in past tense, i.e.Button Clicked,Page Viewed,File Downloaded.UseTitle Case.Frontend only sends two Mixpanel events:Button/Link ClickedandPage Viewed. We then construct custom events such asPassword Reset Button ClickedorPricing Page Viewedinside Mixpanel dashboard based on button name, URL, etc. Custom events can be modified retroactively, regular events cannot.Backend sends "action" events, when those actions finish successfully, such asSite Deployed,PDF generated,Backup Completed.More onhttps://segment.com/academy/collecting-data/naming-conventions-for-clean-data/.Running testsYou need to havepipenvand Python 3.7 installed on your machine. Then you can run:$ make testsRelated packagesThese packages are in the same problem-space:old release of pyramid_mixpanelby @hadrien had some neat ideas that this project built upon, even though it is a complete rewrite;the officialmixpanel-pythonis a lower-level library that this project depends on;mostly deprecatedMixpanel-apifor querying data, superseded byJQL;mixpanel-jqlprovides a Pythonic interface to writing JQL queries.Use in the wildA couple of projects that use pyramid_mixpanel in production:WooCart- Managed WooCommerce service.EasyBlogNetworks- PBN hosting and autopilot maintenance.Kafkai- AI generated content.Docsy- Faceted search for private projects and teams.Changelog0.12.0 (2022-03-22)Overhauled testing support for more readable asserts. This is a breaking
change for existing test cases.
[zupo]0.11.0 (2022-02-10)Support for skipping arbitrary track/profile_set calls to Customer.io.
[zupo]0.10.2 (2021-12-13)Customer.io expects the main "sign up" timestamp to be sent ascreated_at.
[zupo]0.10.1 (2021-12-13)Fix another brownbag release by re-applying fixes from 0.9.1.
[zupo]0.10.0 (2021-12-13)Support different date formatting between Mixpanel and Customer.io.
[zupo]0.9.1 (2021-09-24)Fix brownbag release by fixing definition of extras.
[zupo]0.9.0 (2021-09-24)Add optional support for Customer.io.
[zupo]0.8.0 (2020-05-11)Make structlog optional.
[am-on]Support setting event props from HTTP headers.
[am-on]0.7.0 (2019-12-19)Added support forpeople_union().
[am-on]Addedsayanarijit/typecov.
[sayanarijit]0.6.0 (2019-08-26)Added support for configuring a custom Consumer.
[zupo]0.5.0 (2019-08-25)Require that all Consumers implement aflush()method.
[zupo]0.4.3 (2019-08-24)Include py.typed in the package, third time is the charm?
[zupo]0.4.2 (2019-08-24)Include py.typed in the package, now for real.
[zupo]0.4.1 (2019-08-24)Include py.typed in the package.
[zupo]0.4.0 (2019-08-19)Prepare for PYPI release of the rewrite.
[zupo]Small performance optimization.
[zupo]0.3.0 (2019-08-09)Add guards that make sure parameters sent to MixpanelTrack are valid.
[zupo]Don't flood logs with "mixpanel configured" messages.
[zupo]Support for thepeople_appendmethod.
[suryasr007]Lots of cleanup of legacy assumptions:profile_syncmethod was removedrequest.user no longer requiredMixpanelTrack init now acceptsdistinct_idinstead ofuserstateProfileProperty no longer required
[zupo]0.2.1 (2019-07-28)Not all consumers have a .flush() method.
[zupo]0.2.0 (2019-07-27)Rewrite based on 5 years of Mixpanel usage in production at Niteo.
[@zupo, @vanclevstik, @dz0ny, @karantan, @am-on, @rokcarl]0.1.14 - 0.1.65 (2012-2014)Legacy version developed by @hadrien.