Explore

Kate Santo Updated by Kate Santo

In apps built by Padoq, the Explore functionality allows users to discover new padoqs and connect with people who have similar interests.

Find out how this works from a technical point of view in this guide.

If you'd like to see how we explain this functionality to end users, have a look at the user version of this guide.

Prerequisites

  • You can download the iOS or Android app on your phone to see what the user sees. And you can also log in or sing up to the web app here
  • You can also see the UI by checking out the images you'll find in the guide
  • You will find the relevant endpoints linked and explained in this guide, but the full API is documented in Swagger UI

Journey

1. User opens Explore

Once the user is authenticated in the app, they tap the Explore option. This calls the getPadoqs endpoint, which fetches details of padoqs that might be of interest to the user. There are a few bits of information required for this to work: the padoq's privacy level, the user's interests, the padoq's interests or categories and privileges:

  1. Privacy level
    Padoqs can have 3 possible values in their privacyLevel property: public, private and secret. If the padoq was set up as secret, their visible property would be false, so the padoq wouldn't appear in Explore. If the padoq was set up as public or private, their visible property would be true and the padoq would appear in Explore. Find out more about how the privacyLevel property interacts with Explore further down.
  2. User and padoq interests
    1. For the user, interests are set through the updateUser endpoint. This is called when the user selects the topics that they find interesting in the UI. When they send their selection, the interestGroups property in the user profile gets updated:
    2. ​​"interestGroups"​​:​ ​[​
      ​​"Movies"​​,​
      ​​"Technology"​​,​
      ​​"Basketball"​
      ]
    3. For the padoq, there are interests and categories:
      1. In apps like the free Padoq app, each padoq has at least one interest, like football or bags, for example. Each interest belongs to an interest group (sports and shopping, in our examples). In the Explore screen, interest groups appear at the top. Each interest group, when tapped, returns a list of all the padoqs that belong to that group. The list is ordered by the specific interests
      2. In apps we build for other businesses (namespaces), we use categories instead of interests. Each namespace has a set of categories that are relevant for the business. Padoqs can belong to one or more of these categories. In the Explore view, the getPadoqCategories returns all categories available in the app. And the padoqs appear grouped by category in the UI
    4. So when there are user interestGroups, they get passed to the getPadoqs endpoint via thegroup parameter. If the interestGroups property in the user profile is empty (because the user never selected any interests), the getPadoqs endpoint will return the top 100 padoqs with the highest member count. This ensures that the Explore page doesn't appear empty. And if the app has a predefined list of categories instead, when the user taps on one of them, that category is passed to the getPadoqs endpoint via the category parameter
    5. The returned payload might look something like this:
    6. {
      "padoqs": [
      {
      "name": "my-place",
      "title": "My Place",
      "colour": "pink",
      "exploreGroup": "string",
      "description": "A description of this padoq.",
      "location": {
      "name": "Europe/Manchester",
      "coordinates": [
      53.466667,
      -2.233333 ]
      },
      "memberCount": 100,
      "uri": "https://my-place.padoq.com/padoq/",
      "official": true,
      "visible": false,
      "pending": false,
      "sponsored": false,
      "interests": [
      "Music",
      "Food & Drink",
      "Travel" ],
      "imageUri": "https://media.padoq.com/avatar/66570917-c4d5-430d-ad2b-99bdd1eaf795" }
      ]
      }
  3. Privileges
    1. For padoqs that have privileges defined in their permittedPrivileges property, the user will only see the padoq if they themselves have the same privileges (in a user, these are also stored in a property called permittedPrivileges)
    2. For example, a padoq might live in a namespace that has 3 levels of privilege: basic, silver and gold. If the padoq has a privilege level of gold, only users who have that same level in their profile will be able to find it and join
    3. The endpoint that fetches the available privileges in a namespace is getUserPrivileges (despite its name, privileges are defined and live in the namespace, not the user)
    4. If a padoq has privileges that the user doesn't have, the getPadoqs endpoint wouldn't return a result. If the user is in a namespace or app where none of the padoqs match their privilege, they would see an empty Explore page. A way around this is using the getPadoq endpoint instead. getPadoq lives in the Resource API, and not in the Authentication and Authorization API like getPadoqs. So the user's privileges aren't checked. Therefore, getPadoq can return padoqs that don't match the user's privilege. This can be particularly useful if the admin of the app wants to entice users to get a membership or upgrade their existing level

The explore page shows some details about a padoq, taken from the returned payload: on mobile devices, it's usually its name and avatar. On the upcoming web design, it's that plus its description and location, if available. Also, there is an option to have adds on Explore. If an app has adds configured the getAdverts endpoint will fetch them. Here's how the UI might look like with adverts:

2. The user taps a padoq

When the user taps a specific padoq, they will be taken to a new screen where they can see more about that padoq. Users will see different information depending on how the app and the padoq are set up:

  1. The padoq privacy level
    1. For padoqs that are public, the user (non member at this point) will see posts, but won't be able to interact with the padoq, its posts or view members
    2. For padoqs that are private, the user will see very few details: the padoq's name, its avatar, its member count, and a button to join
  2. Guest access
    1. If there is guest access set up for a namespace, the user will see everything that has been made available for guests in a padoq. That's posts where the recipientRoles property has a value of guest
    2. For example, for apps that have paid subscriptions, the padoq admin might set up a few posts that guests can see, including a post to pay for a subscription. When they subscribe, they will have access to all of the posts where the recipientRoles property has a value of member
    3. It's important to note that a namespace might allow guest access, but not all padoqs need to split their content for different roles. In a namespace that allows guest access, users can find padoqs that are public and that require no subscription to view its full content

3. The user requests to join a padoq

When the user taps the Join button on a padoq, an activity type of MEMBERSHIP_REQUEST is sent to the padoq admin (read more about activities in our guide). A few different things can happen at this point, depending on how the padoq is set up:

  1. If the padoq was set up as public, the user will be able to join without the padoq admin having to approve the request
  2. If the padoq was set up as secret, the user wouldn't even be here as the padoq wouldn't come up in Explore or in search. Users can only join via an invite link
  3. If the padoq was set up as private, the admin needs to approve requests to join. So, depending on how the admin handles the MEMBERSHIP_REQUEST notification, the user will then receive a MEMBERSHIP_ACCEPTED notification or a MEMBERSHIP_REJECTED notification
    1. Read more about this and how padoqs are created in general in our Creating a padoq guide

On top of that, the padoq creator or admin might have set up some questions for all members to answer. In the documentation, this is called 'required information'. If the padoq is public, users can complete required information after joining. If the padoq is private, the user will have to complete the required information when they request to join. When the requesting user completes the required information, their answers are stored in the personaDetails schema. Admins can see the answers from all members via the getPersonas endpoint

4. The user becomes a member of the padoq

If the admin replied to the user's MEMBERSHIP_REQUEST with a MEMBERSHIP_ACCEPTED response, the role of the user in the padoq will change from guest to member. This means that the user can now see all posts with a member value in the recipientRoles property (find it in the model-Post schema)

How did we do?

App menus

Padoq feed and menus

Contact