Key learnings and pitfalls from building mobile SDK

Are you working on the client library? Or design a public API for the module that is going to be used by other team or department?

In this session, Vitality will share his experience and key learnings from building a set of mobile SDKs. The session will be interesting for Android and iOS developers who want to learn what makes client library great. What are the best practices and common pitfalls in public API design. What is important, only programming API you expose or also ecosystem around?

Transcript

1. @zasadnyy
   Or what did we learn in the last 4 years
   Building mobile SDK
   Vitaliy Zasadnyy
   Head of Mobile @ GetSocial
   

   View Slide

2. @zasadnyy
   Integrated SDK.
   But it doesn’t work.
   

   View Slide

3. Developer.
   GDG Lead.
   Public Speaker.
   @zasadnyy
   

   View Slide

4. View Slide

5. View Slide

6. View Slide

7. LISTEN
   

   View Slide

8. SDK Lifecycle
   

   View Slide

9. @zasadnyy
   SDK Lifecycle
   Develop
   1
   

   View Slide

10. @zasadnyy
    

    View Slide

11. @zasadnyy
    SDK Lifecycle
    Develop
    1
    

    View Slide

12. @zasadnyy
    SDK Lifecycle
    Develop
    1
    Integrate
    2
    Support
    3
    Update
    4
    

    View Slide

13. Develop
    1
    

    View Slide

14. @zasadnyy
    Start shaping your API
    Use Cases
    Examples
    Integration Tests
    

    View Slide

15. @zasadnyy
    Cost of fixing issue
    

    View Slide

16. @zasadnyy
    Cost of fixing issue
    Spend 10x more time
    on line of examples
    comparing to
    production code
    

    View Slide

17. @zasadnyy
    NOT SURE?
    DROP IT!
    

    View Slide

18. @zasadnyy
    IS BETTER
    LESS CODE
    

    View Slide

19. @zasadnyy
    Boilerplate ➡ Copy/Paste ➡ Bugs
    Why?
    

    View Slide

20. @zasadnyy
    GetSocial Analytics problem
    Almost all our clients mis-integrate analytics
    
    
    
    
    
    

    View Slide

21. @zasadnyy
    How to solve?
    AndroidManifest merging
    Gradle plugin
    Android Studion plugin
    …
    

    View Slide

22. @zasadnyy
    IS BETTER
    LESS CODE
    

    View Slide

23. @zasadnyy
    API SURPRISES
    AVOID
    

    View Slide

24. @zasadnyy
    Avoid API surprises
    Thread.interrupted()
    Returns the current interrupted status
    and then clears it
    

    View Slide

25. @zasadnyy
    Avoid API surprises
    

    View Slide

26. @zasadnyy
    Avoid API surprises
    Thread.interrupted()
    Returns the current interrupted status
    and then clears it
    

    View Slide

27. @zasadnyy
    Make the API to your library
    as boring as possible
    - Chris Sells, Google
    

    View Slide

28. @zasadnyy
    No SetListener() in C#
    void SetOnInviteFriendsListener (
    Action onInviteFriendsIntent,
    Action onFriendsInvited)
    

    View Slide

29. @zasadnyy
    Much better API
    event Action OnInviteFriendsIntent
    event Action OnFriendsInvited
    

    View Slide

30. @zasadnyy
    Follow platform guidelines
    Mimic core API
    Avoid introducing new concepts
    

    View Slide

31. @zasadnyy
    ?
    Library is crashing
    you app?
    

    View Slide

32. @zasadnyy
    

    View Slide

33. @zasadnyy
    CRASH HOST APP
    NEVER
    

    View Slide

34. @zasadnyy
    GetSocial approach
    Rx
    @Nullable
    PMD / FindBugs / Lint
    

    View Slide

35. @zasadnyy
    Rx chains
    Observable
    .just(MetaDataKey.APP_ID)
    .map(ValidateAppIdFunc.create())
    .flatMap(TrackInstallFunc.create())
    ...
    .subscribe((result) -> { ... },
    (throwable) -> {
    // all exceptions end up here
    }
    );
    

    View Slide

36. @zasadnyy
    Rx chains
    Observable
    .just(MetaDataKey.APP_ID)
    .map(ValidateAppIdFunc.create())
    .flatMap(TrackInstallFunc.create())
    ...
    .subscribe((result) -> { ... },
    (throwable) -> {
    // all exceptions end up here
    }
    );
    

    View Slide

37. @zasadnyy
    

    View Slide

38. @zasadnyy
    INTERNALS
    HIDE
    

    View Slide

39. @zasadnyy
    Hide internals
    

    View Slide

40. @zasadnyy
    Hide internals
    Use .internal package
    Keep everything private by default
    

    View Slide

41. @zasadnyy
    There is much more!
    

    View Slide

42. Integrate
    

    View Slide

43. @zasadnyy
    ?
    What is important
    to developers?
    

    View Slide

44. @zasadnyy
    SIZE
    

    View Slide

45. @zasadnyy
    List information about
    Library size
    Method count
    Proguard rules
    

    View Slide

46. @zasadnyy
    COMPATIBILITY
    

    View Slide

47. @zasadnyy
    Keep compatibility
    Select minimum supported platform version.
    After detailed market research
    Update maximum supported version.
    Continuously
    

    View Slide

48. @zasadnyy
    SUPPORT
    

    View Slide

49. @zasadnyy
    Give a voice to your users
    GitHub issue tracker
    Intercom
    Support email
    …
    

    View Slide

50. @zasadnyy
    Get ready to repetitive
    questions
    

    View Slide

51. @zasadnyy
    DOCS
    

    View Slide

52. @zasadnyy
    Key parts
    Step by step tutorials
    Product guides
    API Reference
    

    View Slide

53. @zasadnyy
    

    View Slide

54. @zasadnyy
    

    View Slide

55. @zasadnyy
    

    View Slide

56. @zasadnyy
    What is wrong with snippet?
    CurrentUser user = getSocial.getCurrentUser();
    

    View Slide

57. @zasadnyy
    What is wrong with snippet?
    CurrentUser user = getSocial.getCurrentUser();
    

    View Slide

58. @zasadnyy
    ALL SNIPPETS MUST
    COMPILE
    

    View Slide

59. @zasadnyy
    Better snippet
    import im.getsocial.sdk.GetSocial;
    import im.getsocial.sdk.CurrentUser;
    ...
    CurrentUser user =
    GetSocial.getInstance().getCurrentUser();
    

    View Slide

60. @zasadnyy
    ?
    Favourite source
    of copy / paste code?
    

    View Slide

61. @zasadnyy
    

    View Slide

62. @zasadnyy
    DEMOS
    

    View Slide

63. @zasadnyy
    Demo apps
    Make demos well documented
    Keep SDK integration code separated
    

    View Slide

64. Support
    

    View Slide

65. @zasadnyy
    ?
    You’ve got support request.
    Now what?
    

    View Slide

66. @zasadnyy
    Two types of problems
    Integration time
    problems
    End-user side
    problems
    

    View Slide

67. @zasadnyy
    Solving integration time problems
    Easy way to get SDK version
    Debug SDK configuration
    Unique log tag
    Actionable errors
    

    View Slide

68. @zasadnyy
    Actionable errors
    public class GetSocialException
    extends RuntimeException {
    private final int _errorCode;
    …
    }
    

    View Slide

69. @zasadnyy
    Actionable errors
    public class GetSocialException
    extends RuntimeException {
    private final int _errorCode;
    …
    }
    

    View Slide

70. @zasadnyy
    Solving end-user side problems
    Comprehensive logs
    Errors analytics
    

    View Slide

71. @zasadnyy
    Solving end-user side problems
    private void trackError(GetSocialException exception) {
    ...
    AnalyticsTrackManager.trackAnalyticsEvent(
    AnalyticsEventDetails.Name.SDK_ERROR,
    eventProperties);
    }
    

    View Slide

72. @zasadnyy
    s
    THINK ABOUT SUPPORT
    AHEAD
    

    View Slide

73. Update
    

    View Slide

74. @zasadnyy
    ?
    Why developers update
    SDKs?
    

    View Slide

75. @zasadnyy
    Update. Build. And…
    

    View Slide

76. @zasadnyy
    

    View Slide

77. @zasadnyy
    UPDATES
    SMOOTH
    

    View Slide

78. @zasadnyy
    Backward compatibility
    Use @Deprecation cycle
    /**
    * @deprecated use {@link #getAllIdentities()} instead.
    * Method will be removed in SDK v5.0.0.
    */
    @Deprecated
    public List getIdentities() { ... }
    

    View Slide

79. @zasadnyy
    Semantic versioning
    v4.5.1
    Major Minor Bugfix
    

    View Slide

80. @zasadnyy
    Versioned packages
    import okhttp3;
    import im.getsocial.sdk6;
    

    View Slide

81. @zasadnyy
    Versioned packages
    import okhttp3;
    import im.getsocial.sdk6;
    Partial transition
    A/B testing
    

    View Slide

82. @zasadnyy
    Changelog
    Fixed issues
    Added features
    Compatibility changes
    API changes
    

    View Slide

83. @zasadnyy
    

    View Slide

84. To sum up
    

    View Slide

85. @zasadnyy
    SDK Lifecycle
    Develop
    1
    

    View Slide

86. @zasadnyy
    SDK Lifecycle
    Develop Integrate Support Update
    1 2 3 4
    

    View Slide

87. @zasadnyy
    Develop
    1 Integrate
    2
    Support
    3 Update
    4
    Not sure? Drop it!
    Never crash
    Be your own
    customer
    Think ahead Smooth
    

    View Slide

88. @zasadnyy
    API can be you biggest asset
    of liability
    - Joshua Bloch
    Put yourself
    in your customer’s shoes
    - Cesare Rocchi
    

    View Slide

89. @zasadnyy
    Happy dog
    Make developers
    happy again.
    

    View Slide

90. @zasadnyy
    @zasadnyy / zasadnyy.com
    Questions?
    Mulțumesc!
    

    View Slide