The Sonos funnel is how a Sonos user connects their Sonos and Idagio accounts.
The process starts in the Sonos app, where they find our service and try to add it to their Sonos system. From there they are either routed to the Join funnel (found at /sonos/join) or the Login funnel (found at /sonos/login?linkCode=freshCakes). Sonos knows about both of these URLs and they use them to route the users to the correct sub-funnels. As such, changing these URLs should be avoided as much as possible (I don’t actually know if it is a lot of work for the backend team to update these URLs in their configuration but it should at least be kept in mind that URL changes involve changes to the backend as well).
The actual authorisation happens in the Login funnel, where do user clicks a button to post two values to our backend.
This document deals explicitly with what happens in our system and as such won’t discuss the flow within the Sonos app.
This sub-funnel can be accessed at /sonos/join. A user lands here if they click on the Create account (or equivalent) button from within the Sonos app. The implementation can be found in the SonosSignup component. There are 6 distinct steps:
- Benefits (B)
- Trial Opt Out Information (TOI)
- Account Creation (AC)
- Subscribe (S)
- Payment Details (PD)
- Back to Sonos for Login (BS)
The Join funnel is straightforward in that there is no branching based on user traits (as is the case in the Login funnel). The flow is always the same:
(B) —> (TOI) —> (AC) —> (S) —> (PD) —> (BS)
This is the initial screen we show to a new user coming from the Sonos app. The initial design required that the background should be black in contrast to the rest of the funnel. One requirement that is coming from Sonos (at least this is what was communicated to us) is that we need to have a screen/step that features the logos from both companies (co-branding).
This step used to have slightly different design requirements than our normal SignupForm and as a result we have a separate component called SonosSignupForm (initial PR can be found here). But as part of our GDPR compliance efforts we also had to update the SonosSignupForm and lacking a separate design for it, we used the same one from SignupForm. As a result, we should double check and remove the SonosSignupForm.
This uses the shared component PaymentForm.
We have to send users back to the Sonos app so they can now go through the Login funnel. Unfortunately, the way Sonos handles the process forces us to push new users through both funnels.
As mentioned before, this is where the actual connection of two services happen. The Login funnel can be accessed at /sonos/login?linkCode={linkCodeFromSonos}. A user lands here after they click Login to your Idagio account (or equivalent) from within the Sonos app. linkCode is a value supplied by Sonos which is only valid for 7 minutes and is POSTed to our backend for authorisation. Again, there are 6 distinct steps:
- Login (L)
- Trial Opt Out Information (TOI)
- Subscribe (S)
- Payment Details (PD)
- Authorise Sonos (AS)
- Authorisation Complete (AC)
The flow of steps is different for subscribed and non-subscribed users. Note that the user HAS TO “login” even if they are already logged in and the designs should stay the same way (i. e. no sidebar even if the user is logged in). This is a deliberate thing, we need to get a separate Sonos access token from our backend and for this we need the user to enter their login details.
The flow for premium users (paying and trial opt-out):
(L) —> (AS) —> (AC)
The flow for non-premium users:
(L) —> (TOI) —> (S) —> (PD) —> (AS) —> (AC)
Similar to the SonosSignupForm this step uses a custom SonosLoginForm for the same reasons. Again, for the same reasons, it is now obsolete and should be removed.
This uses the shared component PaymentForm.
This is the step where the actual connection between the two services happen. When the user clicks the button we POST the linkCode from Sonos and the Sonos access token we obtained earlier to our backend.
Notice the lack of back button from here on out, there is no point in giving the user the option to move back and forth after this point.
