Roadmap

main

Publish your roadmap inside your app and allow users to vote for upcoming features
AvdLee/Roadmap

RoadmapHeader Copy@1x

⚠️ The countAPI which we use in Roadmap to let users vote has been down for six weeks or so. They're looking into it, but currently roadmap is unfortunately not working. The provider of the countapi has let us know that they don't expect the API to be fixed anytime soon, so we are looking for alternatives.

Have a look at this PR for an alternative that we might introduce as the default soon! #71

Here's a step by step guide to host your own server with Vapor (Swift): https://github.com/valentin-mille/RoadmapBackend

Roadmap

Publish your roadmap inside your app and allow users to vote for upcoming features, without having to create a backend!

Example

RoadmapHeader@1x

Setting up Roadmap

Create a Roadmap JSON

Roadmap works with a remote JSON configuration listing all features and their statuses. We recommend hosting it on GitHub Pages or simplejsoncms.com.

An example JSON looks as follows:

[
    {
        "id": "1",
        "title": "Combine sentences",
        "status": "planned",
        "description" : "You can add a little bit of extra context here."
    },
    {
        "id": "2",
        "title": "Open with Finder support",
        "status": "planned"
    },
    {
        "id": "3",
        "title": "Initial Launch",
        "status": "finished",
        "description" : "Release v1 to the public.",
        "isFinished": true
    }
]

The keys id, title are mandatory and all have to be strings. You can use any value for status or description.

Support For Localization

If you are looking to support localization, then you need to add extra optional parameters in your JSON localizedTitle, localizedDescription and localizedStatus like:

[
  {
    "id": "0",
    "title": "Adding a map",
    "localizedTitle": [
      {
        "language": "ar",
        "value": "اضافة خارطة"
      },
      {
        "language": "en",
        "value": "Adding a map"
      }
    ],
    "status": "planned",
    "localizedStatus": [
      {
        "language": "ar",
        "value": "مجدولة"
      },
      {
        "language": "en",
        "value": "Planned"
      }
    ],
    "description": "some description",
    "localizedDescription": [
      {
        "language": "ar",
        "value": "اضافة خارطة لمعرفة الاماكن القريبة"
      },
      {
        "language": "en",
        "value": "Adding a map to view nearby places"
      }
    ]
  }
]

Keep a list of finished features

If you add isFinished as true to a feature in your JSON, the voting view will be hidden for the users & no API call will be made to fetch votes. This is an optional value and it's default value is false.

Add Roadmap using Swift Package Manager

Add https://github.com/AvdLee/Roadmap.git within Xcode's package manager.

Create a Roadmap Configuration instance

Create a new Roadmap configuration following the documentation:

let configuration = RoadmapConfiguration(
    roadmapJSONURL: URL(string: "https://simplejsoncms.com/api/k2f11wikc6")!
)

Optional you can also handover a request for more advanced endpoints, for example protected by OAuth:

var request = URLRequest(url: URL(string: "https://simplejsoncms.com/api/k2f11wikc6")!)
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("Bearer 1234567890", forHTTPHeaderField: "Authorization")

let configuration = RoadmapConfiguration(
    roadmapRequest: request
)

Use the configuration to construct the view

And use the configuration inside the RoadmapView:

struct ContentView: View {
    let configuration = RoadmapConfiguration(
        roadmapJSONURL: URL(string: "https://simplejsoncms.com/api/k2f11wikc6")!,
        namespace: "yourappname" // Defaults to your apps bundle id
        allowVotes: true, // Present the roadmap in read-only mode by setting this to false
        allowSearching: false // Allow users to filter the features list by adding a searchbar
    )

    var body: some View {
        RoadmapView(configuration: configuration)
    }
}

Post Portrait@1x

Styling

By initializing the RoadmapConfiguration with a RoadmapStyle you can create your own styling.

public struct RoadmapStyle {
    /// The image used for the upvote button
    let upvoteIcon : Image
    
    /// The image used for the unvote button
    let unvoteIcon : Image
    
    /// The font used for the feature
    let titleFont : Font
    
    /// The font used for the count label
    let numberFont : Font
    
    /// The font used for the status views
    let statusFont : Font
    
    /// The tint color of the status view
    let statusTintColor: (String) -> Color
    
    /// The corner radius for the upvote button
    let radius : CGFloat
    
    /// The backgroundColor of each cell
    let cellColor : Color
    
    /// The color of the text and icon when voted
    let selectedForegroundColor : Color
    
    /// The main tintColor for the roadmap views.
    let tintColor : Color
    
    public init(upvoteIcon: Image,
                unvoteIcon: Image,
                titleFont: Font,
                numberFont: Font,
                statusFont: Font,
                statusTintColor: @escaping (String) -> Color = { _ in Color.primary },
                cornerRadius: CGFloat,
                cellColor: Color = Color.defaultCellColor,
                selectedColor: Color = .white,
                tint: Color = .accentColor) {
        
        self.upvoteIcon = icon
        self.titleFont = titleFont
        self.numberFont = numberFont
        self.statusFont = statusFont
        self.statusTintColor = statusTintColor
        self.radius = cornerRadius
        self.cellColor = cellColor
        self.selectedForegroundColor = selectedColor
        self.tintColor = tint
        
    }
}

Post Portrait Copy@1x

Templates

If you don't wan't to configure your own style you can also use one of the templates. You have the option between Standard, Playful, Classy and Technical so pick whichever works best for your app.

Example

struct ContentView: View {
    let configuration = RoadmapConfiguration(
        roadmapJSONURL: URL(string: "https://simplejsoncms.com/api/k2f11wikc6")!,
        namespace: "roadmap",
        style: RoadmapTemplate.playful.style, // You can also create your own RoadmapStyle
    )

    var body: some View {
        RoadmapView(configuration: configuration)
    }
}

Persisting Votes

By default, Roadmap will utilise the Free Counting API to store votes, you can check out their website for more information. A namespace is provided for you, utilising your application's bundle identifier, but you can override this when initalising the RoadmapConfiguration.

let configuration = RoadmapConfiguration(
    roadmapJSONURL: URL(string: "https://simplejsoncms.com/api/k2f11wikc6")!,
    namespace: "my-custom-namespace"
)

Defining Custom Voter Service

If you'd rather use your own API, you may create a new struct conforming to FeatureVoter. This has two required functions in order to retrieve the current vote count and to cast a new vote.

struct CustomFeatureVoter: FeatureVoter {
    var count = 0

    func fetch(for feature: RoadmapFeature) async -> Int {
        // query data from your API here
        return count
    }
    
    func vote(for feature: RoadmapFeature) async -> Int? {
        // push data to your API here
        count += 1
        return count
    }
}

You may then pass an instance of this struct to the RoadmapConfiguration.

let configuration = RoadmapConfiguration(
    roadmapJSONURL: URL(string: "https://simplejsoncms.com/api/k2f11wikc6")!,
    voter: CustomFeatureVoter()
)

FAQ

Does Roadmap prevent users from voting multiple times?

Yes, if a user has voted on a feature they won't be able to vote again from within your app. Users can intercept your network traffic and replay the api call if they're really desperate to manipulate your votes.

Can Roadmap be customized to fit the look and feel of my app?

Roadmap comes with four different preconfigured styles to match most apps. You can change the tintColor, upvote image and more.

What OS versions are supported?

To keep development of Roadmap easy and fun, we've decided to support iOS 15 & above and macOS Monterey & Ventura for now.

Can I sort my roadmap by most voted?

Right now the list of features is loaded in random order. Our thinking is that this will prevent bias for the top voted features. We'll look into ways to make this possible in the future but since the votes are retrieved after the view has been loaded we'll need to look into it.

Do I need to make changes to my app privacy report if I use Roadmap?

Roadmap does not do any analytics or tracking. If a user voted on a feature it will increment a number on the count api. No identifiers are stored, not even anonymous ones.

Is it possible for stupid people to manipulate my roadmap?

Yes, we wanted to keep Roadmap as simple as possible to setup. If you're worried about competitors (or a user that really wants a specific feature) messing with your priority list, maybe use something else.

Can I help contribute?

Yes, please! We would love to invite you to pick up any of the open issues. We'll review your Pull Requests accordingly.

Projects using Roadmap

If you've integrated Roadmap into your app and you want to add it to this list, please make a Pull Request.

Authors

This library is created in collaboration between Jordi Bruin, Hidde van der Ploeg, and Antoine van der Lee

License

Roadmap is available under the MIT license. See the LICENSE file for more info.

Description

  • Swift Tools 5.7.0
View More Packages from this Author

Dependencies

  • None
Last updated: Wed Nov 20 2024 22:29:31 GMT-1000 (Hawaii-Aleutian Standard Time)